diff --git a/cmd/container_test.go b/cmd/container_test.go index 00a2ad604d..d3ad72fe3a 100644 --- a/cmd/container_test.go +++ b/cmd/container_test.go @@ -23,8 +23,16 @@ func TestContainerInfoFailureRendering(t *testing.T) { var out bytes.Buffer root.SetOut(&out) root.SetArgs([]string{ - containerCommandName, infoCommandName, "--home", t.TempDir(), - "--context", "not-configured", "--provider", "not-configured", "--result-format", "json", + containerCommandName, + infoCommandName, + "--home", + t.TempDir(), + "--context", + "not-configured", + passiveTestProviderFlag, + "not-configured", + "--result-format", + "json", }) err := root.Execute() require.ErrorContains(t, err, config.EnvWorkspaceID) diff --git a/cmd/dependency/dependency.go b/cmd/dependency/dependency.go new file mode 100644 index 0000000000..53b4cf70c3 --- /dev/null +++ b/cmd/dependency/dependency.go @@ -0,0 +1,17 @@ +// Package dependency provides passive inspection of installed provider dependencies. +package dependency + +import ( + "github.com/devsy-org/devsy/cmd/flags" + "github.com/spf13/cobra" +) + +func NewDependencyCmd(globalFlags *flags.GlobalFlags) *cobra.Command { + command := &cobra.Command{ + Use: "dependency", Short: "Inspect installed provider dependencies", + } + flags.MarkPassive(command) + flags.MarkDependencyInspection(command) + command.AddCommand(newInspectCmd(globalFlags)) + return command +} diff --git a/cmd/dependency/inspect.go b/cmd/dependency/inspect.go new file mode 100644 index 0000000000..636a8fed59 --- /dev/null +++ b/cmd/dependency/inspect.go @@ -0,0 +1,326 @@ +package dependency + +import ( + "context" + "encoding/json" + "errors" + "fmt" + "os" + "runtime" + "time" + + "github.com/devsy-org/devsy/cmd/flags" + "github.com/devsy-org/devsy/pkg/clierr" + "github.com/devsy-org/devsy/pkg/config" + "github.com/devsy-org/devsy/pkg/dependencies" + "github.com/devsy-org/devsy/pkg/output" + "github.com/devsy-org/devsy/pkg/provider" + "github.com/devsy-org/devsy/pkg/secrets" + "github.com/devsy-org/devsy/pkg/workspace" + "github.com/spf13/cobra" +) + +const policyBlocked clierr.Code = "dependency_policy_blocked" + +type inspectOptions struct { + globalFlags *flags.GlobalFlags + forProvider string + asJSON bool +} + +func newInspectCmd(globalFlags *flags.GlobalFlags) *cobra.Command { + options := &inspectOptions{globalFlags: globalFlags} + command := &cobra.Command{ + Use: "inspect ", + Short: "Inspect a saved provider dependency without executing it", + SilenceUsage: true, + Long: "Inspect docker, podman, apple-container, or kubernetes-config for an installed provider. " + + "Reads configuration and filesystem metadata without executing tools, contacting endpoints, or changing selection.", + Args: inspectArgs, + RunE: options.run, + } + command.Flags(). + StringVar(&options.forProvider, "for-provider", "", "Inspect this installed provider without changing the default") + command.Flags().BoolVar(&options.asJSON, "json", false, "Print one dependency report as JSON") + flags.MarkPassive(command) + flags.MarkDependencyInspection(command) + command.SetFlagErrorFunc(func(_ *cobra.Command, _ error) error { + return errors.New("invalid dependency inspection flags") + }) + return command +} + +func inspectArgs(_ *cobra.Command, args []string) error { + if len(args) != 1 { + return errors.New("dependency inspect requires exactly one tool") + } + return nil +} + +func (options *inspectOptions) run(command *cobra.Command, args []string) error { + captured := os.Environ() + cwd, err := os.Getwd() + if err != nil { + return inspectionError(command.Context(), "cannot capture dependency inspection directory") + } + request := inspectionRequest{ + Tool: args[0], ForProvider: options.forProvider, + ForProviderPresent: command.Flags().Changed("for-provider"), + Environment: inspectionEnvironment(captured), WorkingDirectory: cwd, + Metadata: dependencies.PassiveReportMetadata{ + EvaluatedAt: time.Now(), VirtualizationCapability: "not_required", + Redact: secrets.NewEnvironmentRedactor(captured).Redact, + }, + } + mode := output.ModeJSON + if !options.asJSON { + mode, err = output.ResolveMode(options.globalFlags.ResultFormat) + if err != nil { + return errors.New("invalid dependency inspection result format") + } + } + report, err := inspectSavedProvider(command.Context(), request) + if err != nil { + return err + } + if err := command.Context().Err(); err != nil { + return err + } + if mode == output.ModeJSON { + return json.NewEncoder(command.OutOrStdout()).Encode(report) + } + _, err = fmt.Fprintf( + command.OutOrStdout(), + "%s: %s; compatibility: %s; reachability: %s\n%s\n", + report.Items[0].DisplayName, + report.Availability, + report.Compatibility, + report.Reachability, + report.Message, + ) + return err +} + +type inspectionRequest struct { + Tool string + ForProvider string + ForProviderPresent bool + Environment map[string]string + WorkingDirectory string + Metadata dependencies.PassiveReportMetadata +} + +func inspectionError(ctx context.Context, message string) error { + if err := ctx.Err(); err != nil { + return err + } + return &clierr.CLIError{Code: policyBlocked, Message: message} +} + +func inspectSavedProvider( + ctx context.Context, + request inspectionRequest, +) (dependencies.Report, error) { + if err := ctx.Err(); err != nil { + return dependencies.Report{}, err + } + prepared, err := prepareSavedInspection(ctx, request) + if err != nil { + return dependencies.Report{}, err + } + catalog, err := dependencies.LoadCatalog() + if err != nil { + return dependencies.Report{}, inspectionError( + ctx, + "cannot load the dependency inspection catalog", + ) + } + if !inspectionToolMatches(catalog, prepared.Provider.Source, request.Tool) { + return dependencies.Report{}, inspectionError( + ctx, + "tool does not match the installed provider dependency", + ) + } + result, err := workspace.SurveyProviderDependencies(ctx, *prepared) + if err != nil { + return dependencies.Report{}, inspectionError( + ctx, + "cannot survey the installed provider dependency", + ) + } + report, err := catalog.FormatPassiveReport(result, request.Metadata) + if err != nil { + return dependencies.Report{}, inspectionError( + ctx, + "cannot format the dependency inspection report", + ) + } + if err := ctx.Err(); err != nil { + return dependencies.Report{}, err + } + return report, nil +} + +func prepareSavedInspection( + ctx context.Context, + request inspectionRequest, +) (*workspace.ProviderDependencySurveyRequest, error) { + inputs, err := preparedInspectionInputs(ctx) + if err != nil { + return nil, err + } + name, err := selectedProvider( + ctx, + inputs.Config, + request.ForProvider, + request.ForProviderPresent, + ) + if err != nil { + return nil, err + } + installed, err := loadInspectionProvider(ctx, inputs, name) + if err != nil { + return nil, err + } + manifest, stored := installed.manifest, installed.stored + target, err := inspectionTarget(inputs.Config, name, *manifest, stored) + if err != nil { + return nil, inspectionError(ctx, "cannot fingerprint dependency inspection snapshots") + } + prepared, err := workspace.PrepareProviderDependencySurvey( + ctx, + workspace.ProviderDependencyPreparationInput{ + Basis: workspace.ProviderDependencySaved, + Provider: *manifest, + StoredOptions: stored.Options, + DynamicOptions: stored.DynamicOptions, + ExplicitAssignments: map[string]string{}, + Environment: request.Environment, + WorkingDirectory: request.WorkingDirectory, + Target: target, + Host: dependencies.SurveyHost{ + GOOS: runtime.GOOS, + GOARCH: runtime.GOARCH, + }, + }, + ) + if err != nil || prepared.Request == nil { + return nil, inspectionError( + ctx, + "saved provider dependency inspection is blocked by policy", + ) + } + return prepared.Request, nil +} + +type installedInspectionProvider struct { + manifest *provider.ProviderConfig + stored *config.ProviderConfig +} + +func preparedInspectionInputs(ctx context.Context) (flags.PassiveInputs, error) { + inputs, ok := flags.PassiveInputsFromContext(ctx) + if !ok || inputs.Paths == nil || inputs.Config == nil || inputs.Config.Current() == nil { + return flags.PassiveInputs{}, inspectionError( + ctx, + "dependency inspection requires prepared passive inputs", + ) + } + return inputs, nil +} + +func loadInspectionProvider( + ctx context.Context, + inputs flags.PassiveInputs, + name string, +) (installedInspectionProvider, error) { + stored := inputs.Config.Current().Providers[name] + if stored == nil { + return installedInspectionProvider{}, inspectionError( + ctx, + "dependency inspection requires an installed provider record", + ) + } + manifest, err := provider.LoadProviderConfigWithPathManager( + inputs.Paths, + inputs.Config.DefaultContext, + name, + ) + if err != nil || manifest == nil || manifest.Name != name { + return installedInspectionProvider{}, inspectionError( + ctx, + "cannot load the installed dependency inspection provider", + ) + } + if err := ctx.Err(); err != nil { + return installedInspectionProvider{}, err + } + return installedInspectionProvider{manifest: manifest, stored: stored}, nil +} + +func selectedProvider( + ctx context.Context, + snapshot *config.Config, + override string, + present bool, +) (string, error) { + name := snapshot.Current().DefaultProvider + if present { + if override == "" { + return "", errors.New("dependency inspect requires a nonempty --for-provider") + } + name = override + } + invocation := flags.InspectionInvocationFromContext(ctx) + if invocation.ProviderPresent && invocation.Provider != name { + return "", errors.New("--provider conflicts with the dependency inspection target") + } + if name == "" { + return "", inspectionError( + ctx, + "dependency inspection requires an installed provider selection", + ) + } + return name, nil +} + +func inspectionTarget( + snapshot *config.Config, + name string, + manifest provider.ProviderConfig, + stored *config.ProviderConfig, +) (dependencies.SurveyTarget, error) { + configRevision, err := snapshotRevision(snapshot) + if err != nil { + return dependencies.SurveyTarget{}, err + } + providerRevision, err := snapshotRevision(providerSnapshotV1{ + Version: 1, + Manifest: manifest, + StoredOptions: stored.Options, + DynamicOptions: stored.DynamicOptions, + }) + return dependencies.SurveyTarget{ + ContextName: snapshot.DefaultContext, ProviderName: name, + ConfigRevision: configRevision, ProviderConfigRevision: providerRevision, + }, err +} + +// Preparation already verified the complete internal manifest. Match its source +// against the catalog before any executable filesystem lookup can occur. +func inspectionToolMatches( + catalog *dependencies.Catalog, + source provider.ProviderSource, + tool string, +) bool { + if !source.Internal { + return false + } + for _, binding := range catalog.Bindings() { + if binding.Source.Kind == dependencies.SourceInternal && + binding.Source.InternalID == source.Raw { + return len(binding.Requirements) == 1 && binding.Requirements[0].ToolID == tool + } + } + return false +} diff --git a/cmd/dependency/inspect_snapshot.go b/cmd/dependency/inspect_snapshot.go new file mode 100644 index 0000000000..6effdb8391 --- /dev/null +++ b/cmd/dependency/inspect_snapshot.go @@ -0,0 +1,43 @@ +package dependency + +import ( + "crypto/sha256" + "encoding/hex" + "encoding/json" + "strings" + + "github.com/devsy-org/devsy/pkg/config" + "github.com/devsy-org/devsy/pkg/provider" +) + +type providerSnapshotV1 struct { + Version int `json:"version"` + Manifest provider.ProviderConfig `json:"manifest"` + StoredOptions map[string]config.OptionValue `json:"storedOptions"` + DynamicOptions config.OptionDefinitions `json:"dynamicOptions"` +} + +// snapshotRevision fingerprints deterministic Go JSON, not RFC 8785 JSON. +// JSON-visible metadata, slice order and nil/empty follow encoding/json; json:"-" +// fields (origin and transient overrides) are excluded. These local fingerprints +// are not atomic cross-file snapshots, CAS authority, file identity or redaction. +func snapshotRevision(snapshot any) (string, error) { + encoded, err := json.Marshal(snapshot) + if err != nil { + return "", err + } + digest := sha256.Sum256(encoded) + return hex.EncodeToString(digest[:]), nil +} + +func inspectionEnvironment(captured []string) map[string]string { + environment := make(map[string]string, len(captured)) + for _, entry := range captured { + key, value, found := strings.Cut(entry, "=") + if found { + environment[key] = value + } + } + // Preserve differently cased Windows keys for lookup's ambiguity validation. + return environment +} diff --git a/cmd/dependency/inspect_test.go b/cmd/dependency/inspect_test.go new file mode 100644 index 0000000000..615d4f46e6 --- /dev/null +++ b/cmd/dependency/inspect_test.go @@ -0,0 +1,451 @@ +package dependency + +import ( + "bytes" + "context" + "encoding/json" + "io" + "os" + "path/filepath" + "runtime" + "strings" + "testing" + "time" + + "github.com/devsy-org/devsy/cmd/flags" + "github.com/devsy-org/devsy/internal/dependencytest" + "github.com/devsy-org/devsy/pkg/clierr" + "github.com/devsy-org/devsy/pkg/config" + "github.com/devsy-org/devsy/pkg/dependencies" + "github.com/devsy-org/devsy/pkg/provider" + "github.com/devsy-org/devsy/pkg/types" + "github.com/devsy-org/devsy/providers" + "github.com/stretchr/testify/require" + "github.com/stretchr/testify/suite" +) + +const ( + inspectTestDocker = "docker" + inspectTestPodman = "podman" + snapshotSecond = "second" + + inspectTestContext = "chosen" + inspectTestInstallation = "renamed" + inspectTestPATH = "PATH" + inspectTestDockerPath = "DOCKER_PATH" + inspectTestOther = "other" + inspectTestCommand = "inspect" + snapshotFirst = "first" +) + +type inspectSuite struct { + suite.Suite + root string + paths config.PathManager + snapshot *config.Config + manifest *provider.ProviderConfig + metadata dependencies.PassiveReportMetadata +} + +func TestInspect(t *testing.T) { suite.Run(t, new(inspectSuite)) } + +func (s *inspectSuite) SetupTest() { + s.root = s.T().TempDir() + s.T().Setenv(config.EnvConfig, "") + s.paths = config.NewReadOnlyPathManagerForHome(filepath.Join(s.root, "explicit")) + s.snapshot = &config.Config{ + SchemaVersion: 1, + DefaultContext: inspectTestContext, + Contexts: map[string]*config.ContextConfig{ + inspectTestContext: { + DefaultProvider: inspectTestInstallation, + Providers: map[string]*config.ProviderConfig{inspectTestInstallation: {}}, + }, + }, + } + s.manifest = s.install(inspectTestDocker, inspectTestInstallation) + s.saveConfig() + s.metadata = dependencies.PassiveReportMetadata{ + EvaluatedAt: time.Date(2026, 10, 19, 12, 0, 0, 0, time.UTC), + VirtualizationCapability: "not_required", + Redact: func(value string) string { return value }, + } +} + +func (s *inspectSuite) TestAllBuiltinsAndSavedPaths() { + for _, test := range []struct{ builtin, tool, option string }{ + {inspectTestDocker, inspectTestDocker, inspectTestDockerPath}, + {inspectTestPodman, inspectTestPodman, "PODMAN_PATH"}, + {"apple", "apple-container", "CONTAINER_PATH"}, + {"kubernetes", "kubernetes-config", "KUBERNETES_CONFIG"}, + } { + s.Run(test.builtin, func() { + s.install(test.builtin, inspectTestInstallation) + for _, user := range []bool{false, true} { + for _, path := range []string{"", filepath.Join(s.root, "absent"), test.builtin} { + s.snapshot.Current().Providers[inspectTestInstallation].Options = map[string]config.OptionValue{ + test.option: {Value: path, UserProvided: user}, + } + s.saveConfig() + before, err := dependencytest.Tree(s.root) + s.Require().NoError(err) + report, err := s.inspect(test.tool, "", false) + s.Require().NoError(err) + after, err := dependencytest.Tree(s.root) + s.Require().NoError(err) + s.Equal(before, after) + s.Equal(test.tool, report.Items[0].ID) + s.Equal(inspectTestInstallation, report.Target.ProviderName) + s.Equal(test.builtin, report.Target.ProviderType) + s.Equal("unknown", report.Compatibility) + s.Equal("not_checked", report.Reachability) + s.Equal("not_required", report.Host.VirtualizationCapability) + s.Equal(runtime.GOOS, report.Host.GOOS) + s.Empty(report.Actions) + s.False(report.Executed) + s.Regexp("^[0-9a-f]{64}$", report.Target.ConfigRevision) + s.Regexp("^[0-9a-f]{64}$", report.Target.ProviderConfigRevision) + } + } + }) + } +} + +func (s *inspectSuite) TestSavedOptionsIgnoreEnvironmentOverrides() { + bin := filepath.Join(s.root, "bin") + s.Require().NoError(os.Mkdir(bin, 0o700)) + executable := filepath.Join(bin, inspectTestDocker) + marker := filepath.Join(s.root, "EXECUTED") + s.Require().NoError(os.WriteFile(executable, []byte("#!/bin/sh\ntouch '"+marker+"'\n"), 0o600)) + // #nosec G302 -- test-owned sentinel must be executable. + s.Require().NoError(os.Chmod(executable, 0o700)) + s.snapshot.Current().Providers[inspectTestInstallation].Options = map[string]config.OptionValue{ + inspectTestDockerPath: {Value: filepath.Join(s.root, "saved-missing"), UserProvided: true}, + // #nosec G101 -- synthetic endpoint credentials must remain inert and absent from output. + "DOCKER_HOST": {Value: "https://user:credential@127.0.0.1:1"}, + } + s.saveConfig() + dependencytest.Preserve(s.T(), s.root) + manager := config.DefaultPathManager() + report, err := inspectSavedProvider( + s.ctx(), + inspectionRequest{ + Tool: inspectTestDocker, + ForProvider: "", + ForProviderPresent: false, + Environment: map[string]string{ + inspectTestPATH: bin, + inspectTestDockerPath: executable, + "DEVSY_PROVIDER_RENAMED_DOCKER_PATH": executable, + }, + WorkingDirectory: s.root, + Metadata: s.metadata, + }, + ) + s.Require().NoError(err) + s.Equal("missing", report.Availability) + s.Require().Len(report.Items[0].Candidates, 1) + s.Equal(filepath.Join(s.root, "saved-missing"), report.Items[0].Candidates[0].LexicalPath) + s.NoFileExists(marker) + s.Same(manager, config.DefaultPathManager()) + s.snapshot.Current().Providers[inspectTestInstallation].Options = nil + report, err = inspectSavedProvider( + s.ctx(), + inspectionRequest{ + Tool: inspectTestDocker, + ForProvider: "", + ForProviderPresent: false, + Environment: map[string]string{inspectTestPATH: bin}, + WorkingDirectory: s.root, + Metadata: s.metadata, + }, + ) + s.Require().NoError(err) + s.Equal("unknown", report.Availability) + s.NoFileExists(marker) +} + +func (s *inspectSuite) TestSelectionAndCLIProvenance() { + s.install(inspectTestPodman, inspectTestOther) + s.snapshot.Current().Providers[inspectTestOther] = &config.ProviderConfig{} + s.saveConfig() + before, err := json.Marshal(s.snapshot) + s.Require().NoError(err) + report, err := s.inspect(inspectTestPodman, inspectTestOther, true) + s.Require().NoError(err) + s.Equal(inspectTestOther, report.Target.ProviderName) + after, err := json.Marshal(s.snapshot) + s.Require().NoError(err) + s.Equal(before, after) + _, err = s.inspect(inspectTestDocker, "", true) + s.EqualError(err, "dependency inspect requires a nonempty --for-provider") + for _, value := range []string{inspectTestInstallation, ""} { + ctx := flags.WithInspectionInvocation( + s.ctx(), + flags.InspectionInvocation{ProviderPresent: true, Provider: value}, + ) + _, err = inspectSavedProvider( + ctx, + inspectionRequest{ + Tool: inspectTestPodman, + ForProvider: inspectTestOther, + ForProviderPresent: true, + Environment: map[string]string{}, + WorkingDirectory: s.root, + Metadata: s.metadata, + }, + ) + s.EqualError(err, "--provider conflicts with the dependency inspection target") + } + s.snapshot.Current().DefaultProvider = inspectTestOther + report, err = s.inspect(inspectTestPodman, "", false) + s.Require().NoError(err) + s.Equal(inspectTestOther, report.Target.ProviderName) +} + +func (s *inspectSuite) TestPolicyFailures() { + for _, test := range []struct { + name string + change func() + }{ + {"modified", func() { s.manifest.Description += " changed"; s.writeManifest(s.manifest) }}, + {"custom", func() { + s.manifest.Source = provider.ProviderSource{File: "private-secret"} + s.writeManifest(s.manifest) + }}, + {"external", func() { + // #nosec G101 -- synthetic untrusted source credential. + s.manifest.Source = provider.ProviderSource{URL: "https://user:secret@example.test/provider"} + s.writeManifest(s.manifest) + }}, + {"ambiguous", func() { s.manifest.Source.URL = "https://secret@example.test"; s.writeManifest(s.manifest) }}, + {"wrong-installation", func() { + dir, err := s.paths.ProviderDir(inspectTestContext, inspectTestInstallation) + s.Require().NoError(err) + s.manifest.Name = "wrong" + raw, err := json.Marshal(s.manifest) + s.Require().NoError(err) + s.Require().NoError(os.WriteFile(filepath.Join(dir, provider.ProviderConfigFile), raw, 0o600)) + }}, + {"missing-manifest", func() { + dir, err := s.paths.ProviderDir(inspectTestContext, inspectTestInstallation) + s.Require().NoError(err) + s.Require().NoError(os.Remove(filepath.Join(dir, provider.ProviderConfigFile))) + }}, + {"missing-record", func() { delete(s.snapshot.Current().Providers, inspectTestInstallation) }}, + {"dynamic", func() { + s.snapshot.Current().Providers[inspectTestInstallation].DynamicOptions = config.OptionDefinitions{ + inspectTestDockerPath: &types.Option{Command: "secret-command"}, + } + }}, + } { + s.Run(test.name, func() { + s.SetupTest() + test.change() + dependencytest.Preserve(s.T(), s.root) + report, err := s.inspect(inspectTestDocker, "", false) + s.Require().Error(err) + s.Empty(report.Schema) + s.Equal(policyBlocked, clierr.Classify(err).Code) + s.NotContains(err.Error(), "secret") + }) + } +} + +func (s *inspectSuite) TestMismatchPrecedesLookupAndRequiresInputs() { + // A nonexistent cwd would fail preparation if it required filesystem lookup. + _, err := inspectSavedProvider( + s.ctx(), + inspectionRequest{ + Tool: inspectTestPodman, + ForProvider: "", + ForProviderPresent: false, + Environment: map[string]string{}, + WorkingDirectory: filepath.Join(s.root, "no-cwd"), + Metadata: s.metadata, + }, + ) + s.EqualError(err, "tool does not match the installed provider dependency") + _, err = inspectSavedProvider( + s.T().Context(), + inspectionRequest{ + Tool: inspectTestDocker, + ForProvider: "", + ForProviderPresent: false, + Environment: nil, + WorkingDirectory: s.root, + Metadata: s.metadata, + }, + ) + s.EqualError(err, "dependency inspection requires prepared passive inputs") + ctx, cancel := context.WithCancel(s.ctx()) + cancel() + _, err = inspectSavedProvider( + ctx, + inspectionRequest{ + Tool: inspectTestDocker, + ForProvider: "", + ForProviderPresent: false, + Environment: nil, + WorkingDirectory: s.root, + Metadata: s.metadata, + }, + ) + s.ErrorIs(err, context.Canceled) +} + +func (s *inspectSuite) TestCommandOutput() { + s.T().Setenv(inspectTestPATH, "") + for _, args := range [][]string{ + {inspectTestCommand, inspectTestDocker, "--json"}, + {inspectTestCommand, inspectTestDocker, "--json=false"}, + } { + command := NewDependencyCmd(&flags.GlobalFlags{ResultFormat: "json"}) + command.SetContext(s.ctx()) + var out bytes.Buffer + command.SetOut(&out) + command.SetArgs(args) + s.Require().NoError(command.Execute()) + decoder := json.NewDecoder(&out) + decoder.DisallowUnknownFields() + var report dependencies.Report + s.Require().NoError(decoder.Decode(&report)) + s.ErrorIs(decoder.Decode(new(any)), io.EOF) + s.Equal("devsy.dependencies.report.v1", report.Schema) + } + command := NewDependencyCmd(&flags.GlobalFlags{ResultFormat: "plain"}) + command.SetContext(s.ctx()) + var out bytes.Buffer + command.SetOut(&out) + command.SetArgs([]string{inspectTestCommand, inspectTestDocker, "--json=false"}) + s.Require().NoError(command.Execute()) + s.Contains(out.String(), "Docker:") + s.Contains(out.String(), "compatibility: unknown; reachability: not_checked") +} + +func (s *inspectSuite) TestConstructorAndRedactedCandidate() { + dependencytest.Preserve(s.T(), s.root) + NewDependencyCmd(&flags.GlobalFlags{}) + s.snapshot.Current().Providers[inspectTestInstallation].Options = map[string]config.OptionValue{ + inspectTestDockerPath: { + Value: filepath.Join(s.root, "private-candidate"), + UserProvided: true, + }, + } + s.metadata.Redact = func(value string) string { + if strings.Contains(value, "private-candidate") { + return "***" + } + return value + } + report, err := s.inspect(inspectTestDocker, "", false) + s.Require().NoError(err) + s.Empty(report.Items[0].Candidates) + raw, err := json.Marshal(report) + s.Require().NoError(err) + s.NotContains(string(raw), "private-candidate") +} + +func TestSnapshotRevisions(t *testing.T) { + left := map[string]any{"z": []string{snapshotSecond, snapshotFirst}, "a": "value"} + right := map[string]any{"a": "value", "z": []string{snapshotSecond, snapshotFirst}} + a, err := snapshotRevision(left) + require.NoError(t, err) + b, err := snapshotRevision(right) + require.NoError(t, err) + require.Equal(t, a, b) + right["z"] = []string{snapshotFirst, snapshotSecond} + b, err = snapshotRevision(right) + require.NoError(t, err) + require.NotEqual(t, a, b) + manifest := provider.ProviderConfig{Name: "installed", Description: "metadata"} + record := providerSnapshotV1{Version: 1, Manifest: manifest} + a, err = snapshotRevision(record) + require.NoError(t, err) + record.StoredOptions = map[string]config.OptionValue{} + b, err = snapshotRevision(record) + require.NoError(t, err) + require.NotEqual(t, a, b, "record retains nil versus empty") + for _, change := range []func(){ + func() { record.Manifest.Description = inspectTestOther }, + func() { record.StoredOptions[inspectTestPATH] = config.OptionValue{Value: "saved", UserProvided: true} }, + func() { + record.DynamicOptions = config.OptionDefinitions{inspectTestPATH: &types.Option{Default: "dynamic"}} + }, + } { + a, err = snapshotRevision(record) + require.NoError(t, err) + change() + b, err = snapshotRevision(record) + require.NoError(t, err) + require.NotEqual(t, a, b) + } + cfg := &config.Config{DefaultContext: inspectTestContext, Origin: "private"} + a, err = snapshotRevision(cfg) + require.NoError(t, err) + cfg.Origin, cfg.OriginalContext = "different", "original" + b, err = snapshotRevision(cfg) + require.NoError(t, err) + require.Equal(t, a, b) + cfg.DefaultContext = "changed" + b, err = snapshotRevision(cfg) + require.NoError(t, err) + require.NotEqual(t, a, b) + require.Equal( + t, + map[string]string{inspectTestPATH: "last", "Path": "ambiguous"}, + inspectionEnvironment([]string{"PATH=first", "PATH=last", "Path=ambiguous"}), + ) +} + +func (s *inspectSuite) install(builtin, name string) *provider.ProviderConfig { + manifest, err := provider.ParseProvider( + strings.NewReader(providers.GetBuiltInProviders()[builtin]), + ) + s.Require().NoError(err) + manifest.Name = name + manifest.Source = provider.ProviderSource{Internal: true, Raw: builtin} + s.writeManifest(manifest) + return manifest +} + +func (s *inspectSuite) writeManifest(manifest *provider.ProviderConfig) { + dir, err := s.paths.ProviderDir(inspectTestContext, manifest.Name) + s.Require().NoError(err) + s.Require().NoError(os.MkdirAll(dir, 0o700)) + raw, err := json.Marshal(manifest) + s.Require().NoError(err) + s.Require().NoError(os.WriteFile(filepath.Join(dir, provider.ProviderConfigFile), raw, 0o600)) +} + +func (s *inspectSuite) saveConfig() { + path, err := s.paths.ConfigFilePath() + s.Require().NoError(err) + s.Require().NoError(os.MkdirAll(filepath.Dir(path), 0o700)) + raw, err := json.Marshal(s.snapshot) + s.Require().NoError(err) + s.Require().NoError(os.WriteFile(path, raw, 0o600)) + s.snapshot, err = config.LoadConfigWithPathManager(s.paths, inspectTestContext, "") + s.Require().NoError(err) +} + +func (s *inspectSuite) ctx() context.Context { + return flags.WithPassiveInputs( + s.T().Context(), + flags.PassiveInputs{Paths: s.paths, Config: s.snapshot}, + ) +} + +func (s *inspectSuite) inspect(tool, override string, present bool) (dependencies.Report, error) { + return inspectSavedProvider( + s.ctx(), + inspectionRequest{ + Tool: tool, + ForProvider: override, + ForProviderPresent: present, + Environment: map[string]string{inspectTestPATH: ""}, + WorkingDirectory: s.root, + Metadata: s.metadata, + }, + ) +} diff --git a/cmd/flags/inspection.go b/cmd/flags/inspection.go new file mode 100644 index 0000000000..f53096b4df --- /dev/null +++ b/cmd/flags/inspection.go @@ -0,0 +1,45 @@ +package flags + +import ( + "context" + + "github.com/spf13/cobra" +) + +const inspectionAnnotation = "devsy.dependency-inspection" + +// MarkDependencyInspection opts only this command into inspection framing. +func MarkDependencyInspection(command *cobra.Command) { + if command.Annotations == nil { + command.Annotations = map[string]string{} + } + command.Annotations[inspectionAnnotation] = "true" +} + +func IsDependencyInspection(command *cobra.Command) bool { + return command != nil && command.Annotations[inspectionAnnotation] == "true" +} + +// InspectionInvocation records argv intent independently of environment-bound flags. +type InspectionInvocation struct { + JSON bool + ProviderPresent bool + Provider string +} + +type inspectionInvocationKey struct{} + +func WithInspectionInvocation( + ctx context.Context, + invocation InspectionInvocation, +) context.Context { + return context.WithValue(ctx, inspectionInvocationKey{}, invocation) +} + +func InspectionInvocationFromContext(ctx context.Context) InspectionInvocation { + if ctx == nil { + return InspectionInvocation{} + } + invocation, _ := ctx.Value(inspectionInvocationKey{}).(InspectionInvocation) + return invocation +} diff --git a/cmd/flags/inspection_test.go b/cmd/flags/inspection_test.go new file mode 100644 index 0000000000..670267e2d0 --- /dev/null +++ b/cmd/flags/inspection_test.go @@ -0,0 +1,25 @@ +package flags + +import ( + "context" + "testing" + + "github.com/spf13/cobra" + "github.com/stretchr/testify/require" +) + +func TestInspectionPolicyAndContext(t *testing.T) { + group := &cobra.Command{Use: "dependency"} + leaf := &cobra.Command{Use: "inspect"} + group.AddCommand(leaf) + MarkDependencyInspection(group) + require.True(t, IsDependencyInspection(group)) + require.False(t, IsDependencyInspection(leaf)) + require.False(t, IsDependencyInspection(nil)) + require.Empty(t, InspectionInvocationFromContext(context.Background())) + invocation := InspectionInvocation{JSON: true, ProviderPresent: true, Provider: "renamed"} + ctx := WithInspectionInvocation(context.Background(), invocation) + require.Equal(t, invocation, InspectionInvocationFromContext(ctx)) + MarkDependencyInspection(leaf) + require.True(t, IsDependencyInspection(leaf)) +} diff --git a/cmd/flags/passive.go b/cmd/flags/passive.go new file mode 100644 index 0000000000..ac9266adcc --- /dev/null +++ b/cmd/flags/passive.go @@ -0,0 +1,44 @@ +package flags + +import ( + "context" + + "github.com/devsy-org/devsy/pkg/config" + "github.com/spf13/cobra" +) + +const startupPolicyAnnotation = "devsy.passive-startup" + +// MarkPassive opts this command alone into the passive root lifecycle. +// Constructors must mark each leaf separately, including children of marked groups. +func MarkPassive(command *cobra.Command) { + if command.Annotations == nil { + command.Annotations = map[string]string{} + } + command.Annotations[startupPolicyAnnotation] = config.BoolTrue +} + +// IsPassive reports only the command's own static policy, never its ancestors'. +func IsPassive(command *cobra.Command) bool { + return command != nil && command.Annotations[startupPolicyAnnotation] == config.BoolTrue +} + +// PassiveInputs holds caller-owned inputs prepared by the root lifecycle. +// The config remains mutable; the path manager resolves paths without creating roots. +type PassiveInputs struct { + Paths config.PathManager + Config *config.Config +} + +type passiveInputsKey struct{} + +// WithPassiveInputs attaches the prepared inputs for a passive child command. +func WithPassiveInputs(ctx context.Context, inputs PassiveInputs) context.Context { + return context.WithValue(ctx, passiveInputsKey{}, inputs) +} + +// PassiveInputsFromContext returns the inputs after passive root preparation. +func PassiveInputsFromContext(ctx context.Context) (PassiveInputs, bool) { + inputs, ok := ctx.Value(passiveInputsKey{}).(PassiveInputs) + return inputs, ok +} diff --git a/cmd/flags/passive_test.go b/cmd/flags/passive_test.go new file mode 100644 index 0000000000..36e9ed81f0 --- /dev/null +++ b/cmd/flags/passive_test.go @@ -0,0 +1,38 @@ +package flags + +import ( + "context" + "testing" + + "github.com/devsy-org/devsy/pkg/config" + "github.com/spf13/cobra" + "github.com/stretchr/testify/require" +) + +func TestPassiveMarkerDoesNotInherit(t *testing.T) { + parent := &cobra.Command{Use: "parent", Annotations: map[string]string{"unrelated": "retained"}} + child := &cobra.Command{Use: "child"} + parent.AddCommand(child) + MarkPassive(parent) + require.True(t, IsPassive(parent)) + require.Equal(t, "retained", parent.Annotations["unrelated"]) + require.False(t, IsPassive(child)) + require.False(t, IsPassive(nil)) + MarkPassive(child) + require.True(t, IsPassive(child)) +} + +func TestPassiveInputsRemainCallerOwned(t *testing.T) { + ctx := context.Background() + _, ok := PassiveInputsFromContext(ctx) + require.False(t, ok) + inputs := PassiveInputs{ + Paths: config.NewReadOnlyPathManagerForHome(t.TempDir()), + Config: &config.Config{}, + } + prepared := WithPassiveInputs(ctx, inputs) + got, ok := PassiveInputsFromContext(prepared) + require.True(t, ok) + require.Same(t, inputs.Paths, got.Paths) + require.Same(t, inputs.Config, got.Config) +} diff --git a/cmd/inspect_process_unix_test.go b/cmd/inspect_process_unix_test.go new file mode 100644 index 0000000000..479fff24b9 --- /dev/null +++ b/cmd/inspect_process_unix_test.go @@ -0,0 +1,635 @@ +//go:build darwin || linux + +package cmd + +import ( + "bytes" + "context" + "crypto/sha256" + "encoding/hex" + "encoding/json" + "fmt" + "io" + "net/http" + "net/http/httptest" + "os" + "os/exec" + "path/filepath" + "runtime" + "strings" + "sync/atomic" + "testing" + "time" + + "github.com/creack/pty" + "github.com/devsy-org/devsy/internal/dependencytest" + "github.com/devsy-org/devsy/pkg/config" + "github.com/devsy-org/devsy/pkg/dependencies" + "github.com/devsy-org/devsy/pkg/provider" + "github.com/devsy-org/devsy/providers" + "github.com/stretchr/testify/require" +) + +type inspectProcessFixture struct { + root, home, marker string + environment []string + paths config.PathManager + snapshot *config.Config +} + +func newInspectProcessFixture(t *testing.T, proxy string) *inspectProcessFixture { + t.Helper() + t.Setenv(config.EnvConfig, "") + root, err := filepath.EvalSymlinks(t.TempDir()) + require.NoError(t, err) + home := filepath.Join(root, "explicit") + fixture := &inspectProcessFixture{ + root: root, + home: home, + marker: filepath.Join(root, "EXECUTED"), + } + fixture.paths = config.NewReadOnlyPathManagerForHome(home) + fixture.snapshot = &config.Config{ + SchemaVersion: 1, + DefaultContext: inspectTestContext, + Contexts: map[string]*config.ContextConfig{ + inspectTestContext: { + DefaultProvider: "docker-installed", + Providers: map[string]*config.ProviderConfig{}, + }, + }, + } + bin := filepath.Join(root, "bin") + require.NoError(t, os.MkdirAll(bin, 0o700)) + for _, name := range []string{inspectTestDocker, inspectTestPodman, "container", "ioreg", "flatpak-spawn"} { + script := fmt.Sprintf( + "#!/bin/sh\nprintf '%%s\\n' '%s' >> '%s'\nprintf '\"IOPlatformUUID\" = \"T10-FIXTURE-ID\"\\n'\n", + name, + fixture.marker, + ) + // #nosec G306 -- test-owned executable sentinels. + require.NoError(t, os.WriteFile(filepath.Join(bin, name), []byte(script), 0o700)) + } + fixture.installProviders(t, bin) + fixture.environment = append( + passiveProcessEnvironment(root), + "PATH="+bin, + "HTTP_PROXY="+proxy, + "HTTPS_PROXY="+proxy, + "NO_PROXY=", + "ALL_PROXY="+proxy, + "http_proxy="+proxy, + "https_proxy="+proxy, + "no_proxy=", + "all_proxy="+proxy, + "DOCKER_PATH=/environment/decoy", + "DEVSY_PROVIDER_DOCKER-INSTALLED_DOCKER_PATH=/provider/decoy", + ) + // Most fixtures retain a preexisting ambient cache to isolate command behavior. + // The separate fresh-root case verifies startup does not create that cache. + require.NoError(t, os.MkdirAll(filepath.Join(root, "ambient", "cache"), 0o700)) + return fixture +} + +func (fixture *inspectProcessFixture) installProviders(t *testing.T, bin string) { + t.Helper() + bindings := map[string]string{ + inspectTestDocker: "DOCKER_PATH", inspectTestPodman: "PODMAN_PATH", + inspectTestApple: "CONTAINER_PATH", inspectTestKubernetes: "KUBERNETES_CONFIG", + } + for builtin, option := range bindings { + name := builtin + "-installed" + manifest, err := provider.ParseProvider( + strings.NewReader(providers.GetBuiltInProviders()[builtin]), + ) + require.NoError(t, err) + manifest.Name, manifest.Source = name, provider.ProviderSource{Internal: true, Raw: builtin} + fixture.writeManifest(t, name, manifest) + path := filepath.Join(bin, builtin) + if builtin == inspectTestApple { + path = filepath.Join(bin, "container") + } + if builtin == inspectTestKubernetes { + path = filepath.Join(fixture.root, "unparsed-kubeconfig") + require.NoError( + t, + os.WriteFile( + path, + []byte("malformed: [\ncredential-plugin: NEVER_EXECUTE\n"), + 0o600, + ), + ) + } + fixture.snapshot.Current().Providers[name] = &config.ProviderConfig{ + Options: map[string]config.OptionValue{ + option: { + Value: path, + UserProvided: true, + }, + "DOCKER_HOST": {Value: "https://credential@127.0.0.1:1"}, + }, + } + } + fixture.save(t) +} + +func (fixture *inspectProcessFixture) writeManifest( + t *testing.T, + name string, + manifest *provider.ProviderConfig, +) { + t.Helper() + dir, err := fixture.paths.ProviderDir(inspectTestContext, name) + require.NoError(t, err) + require.NoError(t, os.MkdirAll(dir, 0o700)) + raw, err := json.Marshal(manifest) + require.NoError(t, err) + require.NoError(t, os.WriteFile(filepath.Join(dir, provider.ProviderConfigFile), raw, 0o600)) +} + +func (fixture *inspectProcessFixture) save(t *testing.T) { + t.Helper() + path, err := fixture.paths.ConfigFilePath() + require.NoError(t, err) + raw, err := json.Marshal(fixture.snapshot) + require.NoError(t, err) + require.NoError(t, os.WriteFile(path, raw, 0o600)) +} + +func buildInspectMain(t *testing.T) string { + t.Helper() + dir := os.Getenv("DEVSY_T10_EVIDENCE_DIR") + if dir == "" { + dir = t.TempDir() + } + // #nosec G703 -- opt-in evidence directory belongs to the test runner. + require.NoError(t, os.MkdirAll(dir, 0o700)) + binary := filepath.Join(dir, "devsy-inspect-main") + ctx, cancel := context.WithTimeout(t.Context(), 10*time.Minute) + defer cancel() + // #nosec G204 G702 -- fixed repository-main build; runner controls only the output path. + command := exec.CommandContext(ctx, "go", "build", "-o", binary, + "-ldflags=-X github.com/devsy-org/devsy/pkg/version.version=v0.99.0-t10-inspect "+ + "-X github.com/devsy-org/devsy/pkg/telemetry/analytics.posthogAPIKey=test", ".") + command.Dir = ".." + buildOutput, err := command.CombinedOutput() + require.NoError(t, err, "%s", buildOutput) + // #nosec G304 G703 -- read back the actual binary built in the test-owned evidence directory. + raw, err := os.ReadFile(binary) + require.NoError(t, err) + digest := sha256.Sum256(raw) + t.Logf("actual main binary: %s sha256=%s", binary, hex.EncodeToString(digest[:])) + return binary +} + +func (fixture *inspectProcessFixture) run( + t *testing.T, + binary string, + args []string, +) (string, string, int) { + t.Helper() + ctx, cancel := context.WithTimeout(t.Context(), 20*time.Second) + defer cancel() + master, tty, err := pty.Open() + require.NoError(t, err) + defer func() { require.NoError(t, master.Close()) }() + defer func() { _ = tty.Close() }() + // #nosec G204 -- only isolated fixture argv and the actual test-built main binary. + command := exec.CommandContext( + ctx, + binary, + append([]string{passiveTestHomeFlag, fixture.home}, args...)...) + command.Env, command.Dir = fixture.environment, fixture.root + var stdout, stderr bytes.Buffer + command.Stdout, command.Stderr = &stdout, tty + copied := make(chan struct{}) + go func() { _, _ = io.Copy(&stderr, master); close(copied) }() + err = command.Run() + require.NoError(t, tty.Close()) + <-copied + require.NoError(t, ctx.Err(), "shipped-main timeout") + code := 0 + if err != nil { + var exit *exec.ExitError + require.ErrorAs(t, err, &exit) + code = exit.ExitCode() + } + return stdout.String(), stderr.String(), code +} + +func saveInspectEvidence(t *testing.T, name, stdout, stderr string) { + t.Helper() + dir := os.Getenv("DEVSY_T10_EVIDENCE_DIR") + if dir == "" { + return + } + // #nosec G703 -- runner-owned evidence directory and literal case names. + require.NoError(t, os.WriteFile(filepath.Join(dir, name+".stdout"), []byte(stdout), 0o600)) + // #nosec G703 -- runner-owned evidence directory and literal case names. + require.NoError(t, os.WriteFile(filepath.Join(dir, name+".stderr"), []byte(stderr), 0o600)) +} + +func decodeInspectReport(t *testing.T, stdout string) dependencies.Report { + t.Helper() + var report dependencies.Report + decoder := json.NewDecoder(strings.NewReader(stdout)) + decoder.DisallowUnknownFields() + require.NoError(t, decoder.Decode(&report)) + require.ErrorIs(t, decoder.Decode(new(any)), io.EOF) + require.True(t, strings.HasSuffix(stdout, "\n")) + require.Equal(t, "devsy.dependencies.report.v1", report.Schema) + require.Empty(t, report.Actions) + require.False(t, report.Executed) + require.Equal(t, "unknown", report.Compatibility) + require.Equal(t, "not_checked", report.Reachability) + require.Equal(t, "not_required", report.Host.VirtualizationCapability) + return report +} + +func TestInspectShippedMain(t *testing.T) { + binary := buildInspectMain(t) + var requests atomic.Int64 + proxy := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { + requests.Add(1) + w.WriteHeader(http.StatusBadGateway) + })) + defer proxy.Close() + for _, test := range []struct{ builtin, tool string }{ + {inspectTestDocker, inspectTestDocker}, + {inspectTestPodman, inspectTestPodman}, + {inspectTestApple, "apple-container"}, + {inspectTestKubernetes, "kubernetes-config"}, + } { + t.Run(test.builtin, func(t *testing.T) { + fixture := newInspectProcessFixture(t, proxy.URL) + dependencytest.Preserve(t, fixture.root) + before := requests.Load() + stdout, stderr, code := fixture.run( + t, + binary, + []string{ + inspectTestGroup, + inspectTestLeaf, + test.tool, + inspectTestForProvider, + test.builtin + "-installed", + inspectTestJSON, + }, + ) + require.Zero(t, code, "%s", stderr) + require.Empty(t, stderr) + report := decodeInspectReport(t, stdout) + require.Equal(t, test.builtin, report.Target.ProviderType) + require.Equal(t, test.builtin+"-installed", report.Target.ProviderName) + require.Equal(t, "unknown", report.Availability) + require.Equal(t, before, requests.Load()) + require.NoFileExists(t, fixture.marker) + saveInspectEvidence(t, "report-"+test.builtin, stdout, stderr) + }) + } + testInspectMainCases(t, binary, proxy.URL, &requests) + testInspectMainControls(t, binary, proxy.URL, &requests) + testInspectFreshRoots(t, binary, proxy.URL) +} + +func testInspectFreshRoots(t *testing.T, binary, proxy string) { + t.Helper() + t.Run("fresh-roots-preservation", func(t *testing.T) { + fixture := newInspectProcessFixture(t, proxy) + require.NoError(t, os.Remove(filepath.Join(fixture.root, "ambient", "cache"))) + require.NoError(t, os.Remove(filepath.Join(fixture.root, "ambient"))) + before, err := dependencytest.Tree(fixture.root) + require.NoError(t, err) + stdout, stderr, code := fixture.run( + t, + binary, + []string{inspectTestGroup, inspectTestLeaf, inspectTestDocker, inspectTestJSON}, + ) + require.Zero(t, code, "%s", stderr) + decodeInspectReport(t, stdout) + after, err := dependencytest.Tree(fixture.root) + require.NoError(t, err) + beforeJSON, err := json.Marshal(before) + require.NoError(t, err) + afterJSON, err := json.Marshal(after) + require.NoError(t, err) + saveInspectEvidence(t, "fresh-roots", stdout, stderr) + saveInspectEvidence(t, "fresh-roots-trees", string(beforeJSON), string(afterJSON)) + if !bytes.Equal(beforeJSON, afterJSON) { + t.Error( + "actual main changed fresh ambient roots before Execute; " + + "pkg/platform/client.init calls PlatformCacheDir (retained before/after tree evidence)", + ) + } + }) +} + +//nolint:funlen // The literal argv and fixture matrix keeps framing cases reviewable together. +func testInspectMainCases(t *testing.T, binary, proxy string, requests *atomic.Int64) { + t.Helper() + for _, test := range []struct { + name string + args []string + change func(*testing.T, *inspectProcessFixture) + help, failure, humanError bool + }{ + {name: "default", args: []string{inspectTestGroup, inspectTestLeaf, inspectTestDocker, inspectTestJSON}}, + { + name: "provider-env-default", + args: []string{inspectTestGroup, inspectTestLeaf, inspectTestPodman, inspectTestJSON}, + change: func(_ *testing.T, f *inspectProcessFixture) { + f.environment = append(f.environment, "DEVSY_PROVIDER=podman-installed") + }, + }, + { + name: "env-decoy-override", + args: []string{inspectTestGroup, inspectTestLeaf, inspectTestDocker, inspectTestDockerTarget, inspectTestJSON}, + change: func(_ *testing.T, f *inspectProcessFixture) { + f.environment = append(f.environment, "DEVSY_PROVIDER=podman-installed") + }, + }, + { + name: "cli-conflict", + args: []string{ + inspectTestGroup, + inspectTestLeaf, + inspectTestDocker, + "--provider=podman-installed", + inspectTestDockerTarget, + inspectTestJSON, + }, + failure: true, + }, + { + name: "cli-empty-conflict", + args: []string{ + inspectTestGroup, + inspectTestLeaf, + inspectTestDocker, + "--provider=", + inspectTestDockerTarget, + inspectTestJSON, + }, + failure: true, + }, + { + name: "empty-target", + args: []string{inspectTestGroup, inspectTestLeaf, inspectTestDocker, "--for-provider=", inspectTestJSON}, + failure: true, + }, + { + name: "mismatch", + args: []string{inspectTestGroup, inspectTestLeaf, inspectTestPodman, inspectTestJSON}, failure: true, + }, + { + name: "unknown-before-json", + args: []string{inspectTestGroup, inspectTestLeaf, inspectTestDocker, "--bad", inspectTestJSON}, + failure: true, + }, + { + name: "bad-bool-before-json", + args: []string{inspectTestGroup, inspectTestLeaf, inspectTestDocker, "--debug=bad", inspectTestJSON}, + failure: true, + }, + { + name: "invalid-json", + args: []string{inspectTestGroup, inspectTestLeaf, inspectTestDocker, inspectTestBadJSON}, + failure: true, + }, + { + name: "invalid-json-then-false", + args: []string{inspectTestGroup, inspectTestLeaf, inspectTestDocker, inspectTestBadJSON, inspectTestJSONFalse}, + failure: true, + }, + { + name: "json-false", + args: []string{ + inspectTestGroup, inspectTestLeaf, inspectTestDocker, + inspectTestJSON, inspectTestJSONFalse, "--bad", + }, + failure: true, + humanError: true, + }, + { + name: "json-value", + args: []string{inspectTestGroup, inspectTestLeaf, inspectTestDocker, inspectTestForProvider, inspectTestJSON}, + failure: true, + humanError: true, + }, + { + name: "json-equals-value", + args: []string{inspectTestGroup, inspectTestLeaf, inspectTestDocker, "--for-provider=--json"}, + failure: true, + humanError: true, + }, + { + name: "json-operand", + args: []string{inspectTestGroup, inspectTestLeaf, inspectTestDocker, "--", inspectTestJSON}, + failure: true, + humanError: true, + }, + { + name: "json-false-result-mode", + args: []string{inspectTestGroup, inspectTestLeaf, inspectTestDocker, inspectTestJSONFalse, "--result-format=json"}, + }, + {name: "missing-tool", args: []string{inspectTestGroup, inspectTestLeaf, inspectTestJSON}, failure: true}, + { + name: "bad-log-level", + args: []string{inspectTestGroup, inspectTestLeaf, inspectTestDocker, "--log-level=credential", inspectTestJSON}, + failure: true, + }, + { + name: passiveTestHelp, + args: []string{inspectTestGroup, inspectTestLeaf, passiveTestHelpFlag, inspectTestJSON}, help: true, + }, + {name: "help-target", args: []string{passiveTestHelp, inspectTestGroup, inspectTestLeaf}, help: true}, + {name: "group-help", args: []string{inspectTestGroup, passiveTestHelpFlag}, help: true}, + { + name: "missing", + args: []string{inspectTestGroup, inspectTestLeaf, inspectTestDocker, inspectTestJSON}, + change: func(t *testing.T, f *inspectProcessFixture) { + f.snapshot.Current().Providers["docker-installed"].Options["DOCKER_PATH"] = config.OptionValue{ + Value: filepath.Join(f.root, "absent"), UserProvided: true, + } + f.save(t) + }, + }, + { + name: "empty-path", + args: []string{inspectTestGroup, inspectTestLeaf, inspectTestDocker, inspectTestJSON}, + change: func(t *testing.T, f *inspectProcessFixture) { + f.snapshot.Current().Providers["docker-installed"].Options["DOCKER_PATH"] = config.OptionValue{UserProvided: true} + f.save(t) + }, + }, + { + name: "unresolved", + args: []string{inspectTestGroup, inspectTestLeaf, inspectTestDocker, inspectTestJSON}, + failure: true, + change: func(t *testing.T, f *inspectProcessFixture) { + value := f.snapshot.Current().Providers["docker-installed"].Options["DOCKER_PATH"] + value.Children = []string{"DOCKER_PATH"} + f.snapshot.Current().Providers["docker-installed"].Options["DOCKER_PATH"] = value + f.save(t) + }, + }, + { + name: "missing-record", + args: []string{inspectTestGroup, inspectTestLeaf, inspectTestDocker, inspectTestJSON}, + failure: true, + change: func(t *testing.T, f *inspectProcessFixture) { + delete(f.snapshot.Current().Providers, "docker-installed") + f.save(t) + }, + }, + { + name: "missing-manifest", + args: []string{inspectTestGroup, inspectTestLeaf, inspectTestDocker, inspectTestJSON}, + failure: true, + change: func(t *testing.T, f *inspectProcessFixture) { + dir, err := f.paths.ProviderDir(inspectTestContext, "docker-installed") + require.NoError(t, err) + require.NoError(t, os.Remove(filepath.Join(dir, provider.ProviderConfigFile))) + }, + }, + { + name: "untrusted", + args: []string{inspectTestGroup, inspectTestLeaf, inspectTestDocker, inspectTestJSON}, + failure: true, + change: func(t *testing.T, f *inspectProcessFixture) { + // #nosec G101 -- synthetic credential proves source errors are bounded. + f.writeManifest(t, "docker-installed", &provider.ProviderConfig{ + Name: "docker-installed", + Source: provider.ProviderSource{URL: "https://user:credential@example.test/provider"}, + }) + }, + }, + { + name: "inspect-malformed-config", + args: []string{inspectTestGroup, inspectTestLeaf, inspectTestDocker, inspectTestJSON}, + failure: true, + change: func(t *testing.T, f *inspectProcessFixture) { + path, err := f.paths.ConfigFilePath() + require.NoError(t, err) + require.NoError(t, os.WriteFile(path, []byte("contexts: [credential"), 0o600)) + }, + }, + { + name: "pending-deletion", + args: []string{inspectTestGroup, inspectTestLeaf, inspectTestDocker, inspectTestJSON}, + failure: true, + change: func(t *testing.T, f *inspectProcessFixture) { + path, err := f.paths.ConfigFilePath() + require.NoError(t, err) + writePassiveIntent(t, f.home, path, false) + }, + }, + { + name: "context-override", + args: []string{inspectTestGroup, inspectTestLeaf, inspectTestDocker, "--context=chosen", inspectTestJSON}, + }, + { + name: "inspect-external-config", + args: []string{inspectTestGroup, inspectTestLeaf, inspectTestDocker, inspectTestJSON}, + change: func(t *testing.T, f *inspectProcessFixture) { + path := filepath.Join(f.root, "external-config.json") + raw, err := json.Marshal(f.snapshot) + require.NoError(t, err) + require.NoError(t, os.WriteFile(path, raw, 0o600)) + f.environment = append(f.environment, config.EnvConfig+"="+path) + }, + }, + } { + t.Run(test.name, func(t *testing.T) { + fixture := newInspectProcessFixture(t, proxy) + if test.change != nil { + test.change(t, fixture) + } + dependencytest.Preserve(t, fixture.root) + before := requests.Load() + stdout, stderr, code := fixture.run(t, binary, test.args) + switch { + case test.failure: + require.Equal(t, 1, code, "%s %s", stdout, stderr) + require.Empty(t, stdout) + if test.humanError { + require.False(t, json.Valid([]byte(stderr)), "PTY stderr: %s", stderr) + require.Contains(t, stderr, "Error:") + } else { + var envelope map[string]any + require.NoError( + t, + json.Unmarshal([]byte(stderr), &envelope), + "PTY stderr: %s", + stderr, + ) + } + require.NotContains(t, stderr, "credential") + require.NotContains(t, stderr, fixture.root) + case test.help: + require.Zero(t, code, "%s", stderr) + require.Contains(t, stdout, "USAGE:") + require.NotContains(t, stdout, "devsy.dependencies.report.v1") + default: + require.Zero(t, code, "%s", stderr) + report := decodeInspectReport(t, stdout) + if test.name == "missing" { + require.Equal(t, "missing", report.Availability) + } + } + require.Equal(t, before, requests.Load()) + require.NoFileExists(t, fixture.marker) + saveInspectEvidence(t, test.name, stdout, stderr) + }) + } +} + +func testInspectMainControls(t *testing.T, binary, proxy string, requests *atomic.Int64) { + t.Helper() + fixture := newInspectProcessFixture(t, proxy) + stdout, stderr, code := fixture.run(t, binary, []string{"--version"}) + require.Zero(t, code, "%s", stderr) + require.Contains(t, stdout, "v0.99.0-t10-inspect") + saveInspectEvidence(t, "version-control", stdout, stderr) + before := requests.Load() + stdout, stderr, code = fixture.run( + t, + binary, + []string{"provider", cmdList, "--result-format=json"}, + ) + require.Zero(t, code, "%s", stderr) + require.Greater( + t, + requests.Load(), + before, + "ordinary production command must reach rejecting telemetry proxy", + ) + if runtime.GOOS == "darwin" { + raw, err := os.ReadFile(fixture.marker) + require.NoError(t, err) + require.Contains(t, string(raw), "ioreg") + } + saveInspectEvidence(t, "ordinary-control", stdout, stderr) + // Exercise the flatpak-spawn trap directly; no native Flatpak claim follows. + // #nosec G204 -- execute only this fixture-owned positive-control sentinel. + control := exec.CommandContext(t.Context(), filepath.Join(fixture.root, "bin", "flatpak-spawn")) + require.NoError(t, control.Run()) + raw, err := os.ReadFile(fixture.marker) + require.NoError(t, err) + require.Contains(t, string(raw), "flatpak-spawn") + fixture = newInspectProcessFixture(t, proxy) + fixture.environment = append(fixture.environment, "DEVSY_DEBUG=garbage") + stdout, stderr, code = fixture.run( + t, + binary, + []string{inspectTestGroup, inspectTestLeaf, inspectTestDocker, inspectTestJSON}, + ) + require.NotZero(t, code) + require.Empty(t, stdout) + require.False( + t, + json.Valid([]byte(stderr)), + "constructor failures remain outside inspection framing", + ) + saveInspectEvidence(t, "constructor-exclusion", stdout, stderr) +} diff --git a/cmd/invocation_output.go b/cmd/invocation_output.go new file mode 100644 index 0000000000..d61fd57d1a --- /dev/null +++ b/cmd/invocation_output.go @@ -0,0 +1,152 @@ +package cmd + +import ( + "context" + "errors" + "runtime/debug" + "strconv" + "strings" + + "github.com/devsy-org/devsy/cmd/flags" + "github.com/devsy-org/devsy/pkg/clierr" + "github.com/devsy-org/devsy/pkg/log" + "github.com/spf13/cobra" + "github.com/spf13/pflag" +) + +// readInspectionInvocation observes metadata and argv without setters or a second +// Cobra parse. Invalid syntax remains the responsibility of normal execution. +func readInspectionInvocation(command *cobra.Command, args []string) flags.InspectionInvocation { + reader := inspectionReader{command: command} + if !flags.IsDependencyInspection(command) { + return reader.invocation + } + for index := 0; index < len(args); index++ { + arg := args[index] + if arg == "--" { + break + } + if name, long := strings.CutPrefix(arg, "--"); long { + index += reader.longFlag(name, args[index+1:]) + } else if cluster, short := strings.CutPrefix(arg, "-"); short { + index += reader.shortFlags(cluster, args[index+1:]) + } + } + reader.invocation.JSON = reader.invocation.JSON || reader.invalidJSON + return reader.invocation +} + +type inspectionReader struct { + command *cobra.Command + invocation flags.InspectionInvocation + invalidJSON bool +} + +func (reader *inspectionReader) longFlag(argument string, remaining []string) int { + name, value, assigned := strings.Cut(argument, "=") + flag := inspectionFlag(reader.command, name, false) + if flag == nil { + return 0 + } + value, consumed := inspectionFlagValue(flag, value, assigned, remaining) + reader.record(flag, value) + return consumed +} + +func (reader *inspectionReader) shortFlags(cluster string, remaining []string) int { + for len(cluster) > 0 { + flag := inspectionFlag(reader.command, cluster[:1], true) + cluster = cluster[1:] + if flag == nil { + // pflag rejects the entire cluster at the first unknown shorthand. + return 0 + } + if strings.HasPrefix(cluster, "=") || flag.NoOptDefVal == "" { + value, consumed := inspectionFlagValue( + flag, + strings.TrimPrefix(cluster, "="), + len(cluster) > 0, + remaining, + ) + reader.record(flag, value) + return consumed + } + reader.record(flag, flag.NoOptDefVal) + } + return 0 +} + +func inspectionFlag(command *cobra.Command, name string, shorthand bool) *pflag.Flag { + lookup := func(set *pflag.FlagSet) *pflag.Flag { + if shorthand { + return set.ShorthandLookup(name) + } + return set.Lookup(name) + } + if flag := lookup(command.Flags()); flag != nil { + return flag + } + for current := command; current != nil; current = current.Parent() { + if flag := lookup(current.PersistentFlags()); flag != nil { + return flag + } + } + return nil +} + +func inspectionFlagValue( + flag *pflag.Flag, + value string, + assigned bool, + remaining []string, +) (string, int) { + if assigned { + return value, 0 + } + if flag.NoOptDefVal != "" { + return flag.NoOptDefVal, 0 + } + if len(remaining) > 0 { + return remaining[0], 1 + } + return "", 0 +} + +func (reader *inspectionReader) record(flag *pflag.Flag, value string) { + switch flag.Name { + case "json": + parsed, err := strconv.ParseBool(value) + reader.invocation.JSON = parsed + reader.invalidJSON = reader.invalidJSON || err != nil + case "provider": + reader.invocation.ProviderPresent, reader.invocation.Provider = true, value + } +} + +func invocationPanic(recovered any, inspection bool) *clierr.CLIError { + if inspection { + return &clierr.CLIError{ + Code: clierr.CodePanic, + Message: "internal dependency inspection error", + } + } + log.Errorf("panic: %v\n%s", recovered, debug.Stack()) + return clierr.NewPanic(recovered) +} + +func inspectionStartupError(command *cobra.Command, err error) error { + if !flags.IsDependencyInspection(command) { + return err + } + if canceled := command.Context().Err(); canceled != nil { + return canceled + } + if err == nil || + errors.Is(err, context.Canceled) || errors.Is(err, context.DeadlineExceeded) { + return err + } + return &clierr.CLIError{ + Code: clierr.Code("dependency_policy_blocked"), + Message: "cannot prepare passive dependency inspection inputs", + } +} diff --git a/cmd/invocation_output_test.go b/cmd/invocation_output_test.go new file mode 100644 index 0000000000..66193716d6 --- /dev/null +++ b/cmd/invocation_output_test.go @@ -0,0 +1,257 @@ +package cmd + +import ( + "context" + "encoding/json" + "errors" + "io" + "os" + "testing" + + "github.com/devsy-org/devsy/cmd/flags" + "github.com/devsy-org/devsy/pkg/config" + "github.com/spf13/cobra" + "github.com/spf13/pflag" + "github.com/stretchr/testify/require" +) + +const ( + inspectTestPodman = "podman" + inspectTestKubernetes = "kubernetes" + inspectTestGroupAlias = "deps" + inspectTestLeafAlias = "look" + + inspectTestGroup = "dependency" + inspectTestLeaf = "inspect" + inspectTestDocker = "docker" + inspectTestApple = "apple" + inspectTestContext = "chosen" + inspectTestJSON = "--json" + inspectTestJSONFalse = "--json=false" + inspectTestBadJSON = "--json=bad" + inspectTestForProvider = "--for-provider" + inspectTestDockerTarget = "--for-provider=docker-installed" + inspectTestPanic = "panic" + inspectTestCanceled = "canceled" +) + +func inspectionReaderRoot() (*cobra.Command, *cobra.Command, *bool) { + called := false + root := &cobra.Command{Use: "fixture", SilenceErrors: true, SilenceUsage: true} + root.SetOut(io.Discard) + root.SetErr(io.Discard) + root.PersistentFlags().String("provider", "environment-decoy", "") + root.PersistentFlags().Lookup("provider").Changed = true + root.PersistentFlags().StringP("home", "H", "", "") + root.PersistentFlags().BoolP("quiet", "q", false, "") + root.PersistentFlags().CountP("verbose", "v", "") + group := &cobra.Command{Use: inspectTestGroup, Aliases: []string{inspectTestGroupAlias}} + leaf := &cobra.Command{ + Use: inspectTestLeaf, Aliases: []string{inspectTestLeafAlias}, Args: cobra.ArbitraryArgs, + Run: func(_ *cobra.Command, _ []string) { called = true }, + } + leaf.Flags().BoolP("json", "j", false, "") + leaf.Flags().StringP("for-provider", "f", "", "") + flags.MarkDependencyInspection(group) + flags.MarkDependencyInspection(leaf) + flags.MarkPassive(group) + flags.MarkPassive(leaf) + group.AddCommand( + leaf, + &cobra.Command{Use: "active", Run: func(_ *cobra.Command, _ []string) {}}, + ) + root.AddCommand(group) + return root, leaf, &called +} + +func flagStates(command *cobra.Command) map[string]string { + states := map[string]string{} + for current := command; current != nil; current = current.Parent() { + for _, set := range []*pflag.FlagSet{current.Flags(), current.PersistentFlags()} { + set.VisitAll(func(flag *pflag.Flag) { + states[flag.Name] = flag.Value.String() + if flag.Changed { + states[flag.Name] += ":changed" + } + }) + } + } + return states +} + +//nolint:funlen // Literal argv matrix covers the audited framing and provenance cases. +func TestInspectionInvocationReader(t *testing.T) { + for _, test := range []struct { + name string + args []string + json bool + provider bool + value string + parseError bool + runs bool + }{ + {"bare", []string{inspectTestDocker, inspectTestJSON}, true, false, "", false, true}, + {"true", []string{"--json=true", inspectTestDocker}, true, false, "", false, true}, + {"false", []string{inspectTestDocker, inspectTestJSONFalse}, false, false, "", false, true}, + {"repeated-false", []string{inspectTestJSON, inspectTestDocker, inspectTestJSONFalse}, false, false, "", false, true}, + {"repeated-true", []string{inspectTestJSONFalse, inspectTestDocker, inspectTestJSON}, true, false, "", false, true}, + {"invalid", []string{inspectTestDocker, "--json=garbage"}, true, false, "", true, false}, + {"invalid-then-false", []string{inspectTestBadJSON, inspectTestJSONFalse}, true, false, "", true, false}, + {"equals-value", []string{inspectTestDocker, "--for-provider=--json"}, false, false, "", false, true}, + { + "separate-value", + []string{inspectTestDocker, inspectTestForProvider, inspectTestJSON}, + false, false, "", false, true, + }, + { + "delimiter", + []string{inspectTestDocker, "--", inspectTestJSON, "--provider=operand"}, + false, false, "", false, true, + }, + {"unknown-before", []string{inspectTestDocker, "--unknown", inspectTestJSON}, true, false, "", true, false}, + {"bad-bool-before", []string{inspectTestDocker, "--quiet=bad", inspectTestJSON}, true, false, "", true, false}, + {"bad-count-before", []string{inspectTestDocker, "-v=bad", inspectTestJSON}, true, false, "", true, false}, + {"cluster", []string{inspectTestDocker, "-qvj"}, true, false, "", false, true}, + {"cluster-value", []string{inspectTestDocker, "-qf--json"}, false, false, "", false, true}, + {"cluster-required", []string{inspectTestDocker, "-qH", inspectTestJSON}, false, false, "", false, true}, + {"short-invalid", []string{"-j=bad", inspectTestJSONFalse}, true, false, "", true, false}, + {"provider", []string{"--provider=renamed", inspectTestDocker, inspectTestJSON}, true, true, "renamed", false, true}, + {"provider-empty", []string{inspectTestDocker, "--provider=", inspectTestJSON}, true, true, "", false, true}, + { + "provider-value", + []string{inspectTestDocker, passiveTestHomeFlag, "--provider=decoy"}, + false, false, "", false, true, + }, + { + "provider-repeat", + []string{"--provider=first", inspectTestDocker, passiveTestProviderFlag, "last"}, + false, true, "last", false, true, + }, + {passiveTestHelp, []string{inspectTestDocker, passiveTestHelpFlag, inspectTestJSON}, true, false, "", false, false}, + } { + t.Run(test.name, func(t *testing.T) { + root, leaf, called := inspectionReaderRoot() + args := append([]string{inspectTestGroup, inspectTestLeaf}, test.args...) + target, remaining := resolveInvocationCommand(root, args) + require.Same(t, leaf, target) + before := flagStates(target) + invocation := readInspectionInvocation(target, remaining) + require.Equal(t, before, flagStates(target), "reader changed flag state") + require.Equal( + t, + flags.InspectionInvocation{ + JSON: test.json, + ProviderPresent: test.provider, + Provider: test.value, + }, + invocation, + ) + root.SetArgs(args) + selected, err := root.ExecuteC() + require.Equal(t, test.parseError, err != nil) + require.Same(t, target, selected) + require.Equal(t, test.runs, *called) + }) + } +} + +func TestInspectionInvocationScope(t *testing.T) { + for _, test := range []struct { + args []string + json bool + passive bool + }{ + {[]string{inspectTestGroupAlias, inspectTestLeafAlias, inspectTestDocker, inspectTestJSON}, true, true}, + {[]string{ + passiveTestHomeFlag, inspectTestGroup, + inspectTestGroupAlias, inspectTestLeafAlias, inspectTestJSON, + }, true, true}, + {[]string{inspectTestGroup, passiveTestHelpFlag}, false, true}, + {[]string{passiveTestHelp, inspectTestGroup, inspectTestLeaf}, false, true}, + {[]string{inspectTestGroup, "active", inspectTestJSON}, false, false}, + {[]string{"__complete", inspectTestGroup, inspectTestLeaf, inspectTestJSON}, false, false}, + } { + root, _, _ := inspectionReaderRoot() + target, remaining := resolveInvocationCommand(root, test.args) + require.Equal(t, test.json, readInspectionInvocation(target, remaining).JSON) + require.Equal(t, test.passive, passiveCommand(target, remaining)) + } +} + +func TestInspectionFramingBeforeOutput(t *testing.T) { + root, leaf, _ := inspectionReaderRoot() + global := &flags.GlobalFlags{} + root.SetContext(flags.WithInspectionInvocation(withInvocationPolicy(context.Background(), true), + readInspectionInvocation(leaf, []string{inspectTestJSON}))) + require.True(t, configureOutput(root, global, false)) + require.True(t, root.SilenceUsage) +} + +func TestInspectionStartupCancellation(t *testing.T) { + command := &cobra.Command{Use: inspectTestLeaf} + flags.MarkDependencyInspection(command) + ctx, cancel := context.WithCancel(context.Background()) + cancel() + command.SetContext(ctx) + require.ErrorIs( + t, + inspectionStartupError(command, errors.New("private-loader-path")), + context.Canceled, + ) + command.SetContext(context.Background()) + require.EqualError(t, inspectionStartupError(command, errors.New("private-loader-path")), + "cannot prepare passive dependency inspection inputs") +} + +func TestInspectionOuterCleanup(t *testing.T) { + for _, mode := range []string{"error", inspectTestPanic, inspectTestCanceled} { + t.Run(mode, func(t *testing.T) { + dir, home := passiveFixtureEnvironment(t) + preservePassiveFixture(t, dir) + originalArgs, originalStderr := os.Args, os.Stderr + t.Cleanup(func() { os.Args, os.Stderr = originalArgs, originalStderr }) + os.Args = []string{ + config.BinaryName, + passiveTestCommand, + inspectTestJSON, + passiveTestHomeFlag, + home, + } + reader, writer, err := os.Pipe() + require.NoError(t, err) + defer func() { require.NoError(t, reader.Close()) }() + os.Stderr = writer + code := runWithRootFactory(func() (*cobra.Command, *flags.GlobalFlags) { + root, global := passiveTestRoot(func(command *cobra.Command, _ []string) error { + require.True(t, flags.InspectionInvocationFromContext(command.Context()).JSON) + if mode == inspectTestPanic { + panic("private-panic-credential") + } + if mode == inspectTestCanceled { + return context.Canceled + } + return errors.New("fixed inspection fixture error") + }) + leaf, _, err := root.Find([]string{passiveTestCommand}) + require.NoError(t, err) + flags.MarkDependencyInspection(leaf) + leaf.Flags().Bool("json", false, "") + return root, global + }) + require.NoError(t, writer.Close()) + os.Stderr = originalStderr + raw, err := io.ReadAll(reader) + require.NoError(t, err) + require.Equal(t, 1, code) + require.True(t, json.Valid(raw), "%s", raw) + require.NotContains(t, string(raw), "private-panic-credential") + if mode == inspectTestCanceled { + var envelope struct { + Code string `json:"code"` + } + require.NoError(t, json.Unmarshal(raw, &envelope)) + require.Equal(t, inspectTestCanceled, envelope.Code) + } + }) + } +} diff --git a/cmd/passive.go b/cmd/passive.go new file mode 100644 index 0000000000..24549ba0c8 --- /dev/null +++ b/cmd/passive.go @@ -0,0 +1,97 @@ +package cmd + +import ( + "context" + "fmt" + + "github.com/devsy-org/devsy/cmd/flags" + "github.com/devsy-org/devsy/pkg/config" + "github.com/devsy-org/devsy/pkg/flatpak" + "github.com/devsy-org/devsy/pkg/log" + "github.com/spf13/cobra" +) + +type passiveInvocationKey struct{} + +// Cobra's Find retains the deepest command even when legacy argument validation +// fails. Its flag metadata must include help before resolving --help paths. +func resolveInvocation(root *cobra.Command, args []string) (*cobra.Command, bool) { + target, remaining := resolveInvocationCommand(root, args) + return target, passiveCommand(target, remaining) +} + +func resolveInvocationCommand(root *cobra.Command, args []string) (*cobra.Command, []string) { + root.InitDefaultHelpCmd() + root.InitDefaultCompletionCmd(args...) + initHelpFlags(root) + target, remaining, _ := root.Find(args) + if target == nil { + target = root + } + return target, remaining +} + +func initHelpFlags(command *cobra.Command) { + command.InitDefaultHelpFlag() + for _, child := range command.Commands() { + initHelpFlags(child) + } +} + +func passiveCommand(command *cobra.Command, args []string) bool { + root := command.Root() + help, _, _ := root.Find([]string{"help"}) + if command == help { + target, _, _ := root.Find(args) + return flags.IsPassive(target) + } + return flags.IsPassive(command) +} + +func passiveInvocation(command *cobra.Command, args []string) bool { + if ctx := command.Context(); ctx != nil { + if passive, ok := ctx.Value(passiveInvocationKey{}).(bool); ok { + return passive + } + } + return passiveCommand(command, args) +} + +func withInvocationPolicy(ctx context.Context, passive bool) context.Context { + return context.WithValue(ctx, passiveInvocationKey{}, passive) +} + +func passiveHostInspection(inSandbox bool) error { + if inSandbox { + return fmt.Errorf( + "passive host inspection is unsupported inside Flatpak; run the host Devsy CLI", + ) + } + return nil +} + +func preparePassive(command *cobra.Command, globalFlags *flags.GlobalFlags) (string, error) { + if err := passiveHostInspection(flatpak.InSandbox()); err != nil { + return "", err + } + paths := config.NewReadOnlyPathManagerForHome(globalFlags.DevsyHome) + if err := config.CheckPendingContextDeletionWithPathManager(paths); err != nil { + return "", err + } + snapshot, err := config.LoadConfigWithPathManager( + paths, + globalFlags.Context, + globalFlags.Provider, + ) + if err != nil { + return "", err + } + command.SetContext(flags.WithPassiveInputs(command.Context(), flags.PassiveInputs{ + Paths: paths, Config: snapshot, + })) + level := snapshot.ContextOption(config.ContextOptionLogLevel) + if level == "" { + level = log.DefaultLevel + } + return level, nil +} diff --git a/cmd/passive_process_test.go b/cmd/passive_process_test.go new file mode 100644 index 0000000000..c4f8d0d58b --- /dev/null +++ b/cmd/passive_process_test.go @@ -0,0 +1,320 @@ +package cmd + +import ( + "context" + "errors" + "fmt" + "net/http" + "net/http/httptest" + "os" + "os/exec" + "path/filepath" + "runtime" + "slices" + "strings" + "sync/atomic" + "testing" + "time" + + "github.com/devsy-org/devsy/cmd/flags" + "github.com/devsy-org/devsy/internal/dependencytest" + "github.com/devsy-org/devsy/pkg/config" + "github.com/devsy-org/devsy/pkg/telemetry" + "github.com/devsy-org/devsy/pkg/telemetry/analytics" + "github.com/devsy-org/devsy/pkg/version" + "github.com/spf13/cobra" + "github.com/stretchr/testify/require" +) + +const ( + processFixtureEnv = "DEVSY_T10_PROCESS_FIXTURE" + processFixtureWindows = "windows" +) + +// This harness runs the outer production lifecycle with test-only commands. +// It cannot replace a shipped main invocation once real passive commands land. +func TestPassiveProcessLifecycle(t *testing.T) { + binary := buildPassiveProcessHelper(t) + var requests atomic.Int64 + proxy := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + if r.Method != http.MethodConnect || r.Host != "us.i.posthog.com:443" { + t.Errorf("unexpected proxy target: %s %s", r.Method, r.Host) + } + requests.Add(1) + w.WriteHeader(http.StatusBadGateway) + })) + defer proxy.Close() + + for _, test := range []struct { + name string + args []string + code int + }{ + {"success", []string{passiveTestCommand}, 0}, + {"run-error", []string{passiveTestCommand}, 1}, + {"panic", []string{passiveTestCommand}, 1}, + {processConstructionPanic, []string{passiveTestCommand}, 1}, + {"alias", []string{"pf"}, 0}, + {passiveTestHelp, []string{passiveTestCommand, passiveTestHelpFlag}, 0}, + {"help-before", []string{passiveTestHelpFlag, passiveTestCommand}, 0}, + {"help-command", []string{passiveTestHelp, "pf"}, 0}, + {"unknown-flag", []string{passiveTestCommand, passiveTestUnknownFlag}, 1}, + {"missing-value", []string{passiveTestCommand, passiveTestHomeFlag}, 1}, + {"bad-value", []string{passiveTestCommand, "--debug=invalid"}, 1}, + {"after-delimiter", []string{passiveTestCommand, "--", passiveTestActive}, 1}, + {"malformed-config", []string{passiveTestCommand}, 1}, + {"pending-deletion", []string{passiveTestCommand}, 1}, + {"invalid-deletion", []string{passiveTestCommand}, 1}, + {"external-config", []string{passiveTestCommand}, 0}, + {"marked-group-help", []string{passiveTestHelp, passiveTestGroup}, 0}, + {"unknown-group-child-help", []string{passiveTestGroup, passiveTestUnknown}, 0}, + {"flag-value-before-leaf", []string{passiveTestHomeFlag, passiveTestGroup, "pf"}, 0}, + } { + t.Run(test.name, func(t *testing.T) { + fixture := newPassiveProcessFixture(t, test.name, proxy.URL) + before := requests.Load() + output, code := fixture.run(t, binary, test.args) + require.Equal(t, test.code, code, "%s", output) + require.Equal(t, before, requests.Load(), "unexpected proxy request") + require.NoFileExists(t, fixture.sentinel) + require.Contains(t, output, "T10_HARNESS_PRESERVED") + }) + } + + testPassiveProcessControls(t, binary, proxy.URL, &requests) +} + +func testPassiveProcessControls(t *testing.T, binary, proxyURL string, requests *atomic.Int64) { + t.Helper() + + t.Run("flatpak-sentinel-positive-control", func(t *testing.T) { + if runtime.GOOS == processFixtureWindows { + t.Skip("shell sentinel is Unix-only") + } + fixture := newPassiveProcessFixture(t, "sentinel-control", proxyURL) + output, code := fixture.run(t, binary, []string{passiveTestCommand}) + require.Zero(t, code, "%s", output) + raw, err := os.ReadFile(filepath.Clean(fixture.sentinel)) + require.NoError(t, err) + require.Contains(t, string(raw), "flatpak-spawn") + }) + + t.Run("ordinary-positive-control", func(t *testing.T) { + fixture := newPassiveProcessFixture(t, "ordinary", proxyURL) + before := requests.Load() + output, code := fixture.run(t, binary, []string{passiveTestGroup, passiveTestActive}) + require.Zero(t, code, "%s", output) + require.Greater( + t, + requests.Load(), + before, + "telemetry proxy trap must detect ordinary recording", + ) + if runtime.GOOS == "darwin" { + raw, err := os.ReadFile(filepath.Clean(fixture.sentinel)) + require.NoError(t, err) + require.Contains(t, string(raw), "ioreg") + } + }) +} + +func buildPassiveProcessHelper(t *testing.T) string { + t.Helper() + binary := filepath.Join(t.TempDir(), "t10-helper") + if runtime.GOOS == processFixtureWindows { + binary += ".exe" + } + ctx, cancel := context.WithTimeout(t.Context(), 10*time.Minute) + defer cancel() + // #nosec G204 -- only the test-owned output path varies in this fixed build command. + cmd := exec.CommandContext( + ctx, + "go", + "test", + "-c", + "-race", + "-o", + binary, + "-ldflags=-X github.com/devsy-org/devsy/pkg/version.version=v0.99.0-t10-fixture "+ + "-X github.com/devsy-org/devsy/pkg/telemetry/analytics.posthogAPIKey=test", + ".", + ) + output, err := cmd.CombinedOutput() + require.NoError(t, err, "%s", output) + return binary +} + +type passiveProcessFixture struct { + environment []string + sentinel string +} + +func newPassiveProcessFixture(t *testing.T, mode, proxy string) passiveProcessFixture { + t.Helper() + root, err := filepath.EvalSymlinks(t.TempDir()) + require.NoError(t, err) + homes := filepath.Join(root, "homes") + require.NoError(t, os.Mkdir(homes, 0o700)) + home := filepath.Join(homes, "explicit") + sentinel := filepath.Join(root, "process-attempts") + environment := passiveProcessEnvironment(homes) + environment = append(environment, + processFixtureEnv+"="+mode, "DEVSY_T10_TREE="+homes, "DEVSY_T10_HOME="+home, + "HTTPS_PROXY="+proxy, "HTTP_PROXY="+proxy, "NO_PROXY=", "ALL_PROXY="+proxy, + "https_proxy="+proxy, "http_proxy="+proxy, "no_proxy=", "all_proxy="+proxy, + ) + if runtime.GOOS != processFixtureWindows { + bin := filepath.Join(root, "bin") + require.NoError(t, os.Mkdir(bin, 0o700)) + for _, name := range []string{"ioreg", "flatpak-spawn"} { + script := fmt.Sprintf( + "#!/bin/sh\nprintf '%%s\\n' '%s' >> '%s'\nprintf '\"IOPlatformUUID\" = \"T10-FIXTURE-ID\"\\n'\n", + name, + sentinel, + ) + // #nosec G306 -- these test-owned process sentinels must be executable. + require.NoError(t, os.WriteFile(filepath.Join(bin, name), []byte(script), 0o700)) + } + environment = append(environment, "PATH="+bin) + } + if strings.Contains(mode, "config") || strings.Contains(mode, "deletion") { + require.NoError(t, os.Mkdir(home, 0o700)) + path := filepath.Join(home, config.ConfigFile) + if mode == "external-config" { + path = filepath.Join(homes, "external-config.yaml") + environment = append(environment, config.EnvConfig+"="+path) + } + require.NoError(t, os.WriteFile(path, []byte("contexts: {}"), 0o600)) + if mode == "malformed-config" { + require.NoError(t, os.WriteFile(path, []byte("contexts: ["), 0o600)) + } + if strings.Contains(mode, "deletion") { + writePassiveIntent(t, home, path, mode == "invalid-deletion") + } + } + return passiveProcessFixture{environment: environment, sentinel: sentinel} +} + +func passiveProcessEnvironment(homes string) []string { + removed := []string{ + "CI", + "TRAVIS", + "GITHUB_ACTIONS", + "GITLAB_CI", + "CIRCLECI", + "TEAMCITY_VERSION", + "BITBUCKET_BUILD_NUMBER", + config.EnvHome, + config.EnvConfig, + config.EnvDisableTelemetry, + config.EnvUI, + config.EnvPlatformRunner, + "HOME", + "USERPROFILE", + "XDG_CONFIG_HOME", + "XDG_DATA_HOME", + "XDG_CACHE_HOME", + "PATH", + "HTTP_PROXY", + "HTTPS_PROXY", + "NO_PROXY", + "ALL_PROXY", + "http_proxy", + "https_proxy", + "no_proxy", + "all_proxy", + } + environment := slices.DeleteFunc(os.Environ(), func(value string) bool { + key, _, _ := strings.Cut(value, "=") + return slices.Contains(removed, key) || strings.HasPrefix(key, "DEVSY_") + }) + for key, subdir := range map[string]string{ + "HOME": "user", "USERPROFILE": "user", config.EnvHome: "ambient", + "XDG_CONFIG_HOME": "config", "XDG_DATA_HOME": "data", "XDG_CACHE_HOME": "cache", + } { + environment = append(environment, key+"="+filepath.Join(homes, subdir)) + } + return append(environment, config.EnvDisableTelemetry+"=false", config.EnvConfig+"=") +} + +func (fixture passiveProcessFixture) run(t *testing.T, binary string, args []string) (string, int) { + t.Helper() + ctx, cancel := context.WithTimeout(t.Context(), 15*time.Second) + defer cancel() + // #nosec G204 -- binary and argv belong to this isolated test fixture. + cmd := exec.CommandContext( + ctx, + binary, + append([]string{"-test.run=^TestPassiveProcessHelper$", "--"}, args...)...) + cmd.Env = fixture.environment + output, err := cmd.CombinedOutput() + require.NoError(t, ctx.Err(), "helper timeout: %.4096s", output) + if err != nil { + var exit *exec.ExitError + require.ErrorAs(t, err, &exit) + return string(output), exit.ExitCode() + } + return string(output), 0 +} + +func TestPassiveProcessHelper(t *testing.T) { + mode := os.Getenv(processFixtureEnv) + if mode == "" { + return + } + require.NotEqual(t, version.DevVersion, version.GetVersion()) + require.NotEqual(t, config.BoolTrue, os.Getenv(config.EnvDisableTelemetry)) + require.False(t, analytics.Dry) + if mode == "sentinel-control" { + cmd := exec.CommandContext(t.Context(), "flatpak-spawn", "--fixture") + require.NoError(t, cmd.Run()) + return + } + index := slices.Index(os.Args, "--") + require.Positive(t, index) + os.Args = append([]string{config.BinaryName}, os.Args[index+1:]...) + if mode != "missing-value" && mode != processConstructionPanic { + os.Args = append(os.Args, passiveTestHomeFlag, os.Getenv("DEVSY_T10_HOME")) + } + environment := dependencytest.Environment() + tree, err := dependencytest.Tree(os.Getenv("DEVSY_T10_TREE")) + require.NoError(t, err) + manager := config.DefaultPathManager() + code := runWithRootFactory(func() (*cobra.Command, *flags.GlobalFlags) { + return processFixtureRoot(t, mode) + }) + if mode != "ordinary" { + require.Equal(t, environment, dependencytest.Environment()) + after, err := dependencytest.Tree(os.Getenv("DEVSY_T10_TREE")) + require.NoError(t, err) + require.Equal(t, tree, after) + require.Same(t, manager, config.DefaultPathManager()) + _, err = fmt.Fprintln(os.Stdout, "T10_HARNESS_PRESERVED") + require.NoError(t, err) + } + os.Exit(code) +} + +func processFixtureRoot(t *testing.T, mode string) (*cobra.Command, *flags.GlobalFlags) { + t.Helper() + if mode == processConstructionPanic { + panic("construction fixture") + } + return passiveTestRoot(func(command *cobra.Command, _ []string) error { + if mode != "ordinary" { + require.Contains( + t, + fmt.Sprintf("%T", telemetry.FromContext(command.Context())), + "noop", + ) + } + switch mode { + case "run-error": + return errors.New("RunE fixture") + case "panic": + panic("RunE fixture") + default: + return nil + } + }) +} diff --git a/cmd/passive_test.go b/cmd/passive_test.go new file mode 100644 index 0000000000..0c1e0af82b --- /dev/null +++ b/cmd/passive_test.go @@ -0,0 +1,338 @@ +package cmd + +import ( + "context" + "encoding/json" + "errors" + "fmt" + "io" + "os" + "path/filepath" + "strings" + "testing" + + "github.com/devsy-org/devsy/cmd/flags" + "github.com/devsy-org/devsy/internal/dependencytest" + "github.com/devsy-org/devsy/pkg/config" + "github.com/devsy-org/devsy/pkg/log" + "github.com/devsy-org/devsy/pkg/telemetry" + "github.com/spf13/cobra" + "github.com/stretchr/testify/require" +) + +const ( + passiveRunError = "run error" + passiveInvalidDeletion = "invalid deletion" + passiveTestCommand = "passive-fixture" + passiveTestGroup = "passive-group" + passiveTestActive = "active" + passiveTestHelpFlag = "--help" + passiveTestHomeFlag = "--home" + passiveTestProviderFlag = "--provider" + passiveTestUnknownFlag = "--unknown" + passiveTestUnknown = "unknown" + passiveTestHelp = "help" + passiveExternalConfig = "external config" + passiveExternalDeletion = "external pending deletion" + processConstructionPanic = "construction-panic" +) + +func passiveTestRoot( + run func(*cobra.Command, []string) error, +) (*cobra.Command, *flags.GlobalFlags) { + root, global := BuildRoot() + leaf := &cobra.Command{ + Use: passiveTestCommand, + Aliases: []string{"pf"}, + Args: cobra.NoArgs, + RunE: run, + } + leaf.Flags().String("fixture-value", "", "fixture value") + flags.MarkPassive(leaf) + group := &cobra.Command{Use: passiveTestGroup} + flags.MarkPassive(group) + group.AddCommand(&cobra.Command{Use: passiveTestActive, RunE: run}) + root.AddCommand(leaf, group) + root.SetOut(io.Discard) + root.SetErr(io.Discard) + return root, global +} + +func TestPassiveDispatch(t *testing.T) { + for _, test := range []struct { + name string + args []string + want bool + }{ + {"leaf", []string{passiveTestCommand}, true}, + {"alias", []string{"pf"}, true}, + {"help flag before leaf", []string{passiveTestHelpFlag, passiveTestCommand}, true}, + {"help flag after leaf", []string{passiveTestCommand, passiveTestHelpFlag}, true}, + {"help command", []string{passiveTestHelp, "pf"}, true}, + {"help global value", []string{passiveTestHelp, passiveTestHomeFlag, passiveTestGroup, "pf"}, true}, + {"help malformed topic", []string{passiveTestHelp, passiveTestCommand, passiveTestUnknown}, true}, + {"unknown leaf flag", []string{passiveTestCommand, passiveTestUnknownFlag}, true}, + {"missing leaf flag value", []string{passiveTestCommand, passiveTestHomeFlag}, true}, + {"invalid boolean", []string{passiveTestCommand, "--debug=invalid"}, true}, + {"unexpected argument", []string{passiveTestCommand, passiveTestUnknown}, true}, + {"argument after delimiter", []string{passiveTestCommand, "--", passiveTestGroup}, true}, + {"delimiter before command", []string{"--", passiveTestCommand}, false}, + {"global value is command", []string{passiveTestHomeFlag, passiveTestCommand}, false}, + {"global value before leaf", []string{passiveTestHomeFlag, passiveTestGroup, "pf"}, true}, + {"unmarked child", []string{passiveTestGroup, passiveTestActive}, false}, + {"unmarked child help", []string{passiveTestHelp, passiveTestGroup, passiveTestActive}, false}, + {"marked group", []string{passiveTestGroup}, true}, + {"group unknown child", []string{passiveTestGroup, passiveTestUnknown}, true}, + {"group child consumed as value", []string{passiveTestGroup, passiveTestHomeFlag, passiveTestActive}, true}, + {"completion", []string{"completion", "bash"}, false}, + {"dynamic completion", []string{"__complete", passiveTestCommand, ""}, false}, + {"unknown prefix consumes leaf", []string{passiveTestUnknownFlag, passiveTestCommand}, false}, + } { + t.Run(test.name, func(t *testing.T) { + root, _ := passiveTestRoot(nil) + _, passive := resolveInvocation(root, test.args) + require.Equal(t, test.want, passive) + }) + } +} + +func passiveFixtureEnvironment(t *testing.T) (string, string) { + t.Helper() + root, err := filepath.EvalSymlinks(t.TempDir()) + require.NoError(t, err) + t.Setenv("HOME", filepath.Join(root, "user")) + t.Setenv("XDG_CONFIG_HOME", filepath.Join(root, "xdg-config")) + t.Setenv("XDG_DATA_HOME", filepath.Join(root, "xdg-data")) + t.Setenv("XDG_CACHE_HOME", filepath.Join(root, "xdg-cache")) + t.Setenv(config.EnvHome, filepath.Join(root, "ambient")) + t.Setenv(config.EnvConfig, "") + return root, filepath.Join(root, "explicit") +} + +func preservePassiveFixture(t *testing.T, root string) { + t.Helper() + manager := config.DefaultPathManager() + dependencytest.Preserve(t, root) + t.Cleanup(func() { require.Same(t, manager, config.DefaultPathManager()) }) +} + +func TestPassiveRootPreparation(t *testing.T) { + states := []string{ + "absent root", + "missing config", + "saved config", + passiveExternalConfig, + passiveRunError, + } + for _, state := range states { + t.Run(state, func(t *testing.T) { + rootDir, home := passiveFixtureEnvironment(t) + configPath := filepath.Join(home, config.ConfigFile) + if state == passiveExternalConfig { + configPath = filepath.Join(rootDir, "external", config.ConfigFile) + t.Setenv(config.EnvConfig, configPath) + } + if state != "absent root" { + require.NoError(t, os.MkdirAll(filepath.Dir(configPath), 0o700)) + } + if state == "saved config" || state == passiveExternalConfig { + writePassiveConfig(t, configPath) + } + preservePassiveFixture(t, rootDir) + called := false + wantErr := errors.New("passive fixture error") + root, _ := passiveTestRoot(func(command *cobra.Command, _ []string) error { + called = true + return checkPassivePreparedInputs( + t, + command, + passiveExpectedInputs{configPath, home, state}, + wantErr, + ) + }) + root.SetArgs( + []string{ + passiveTestCommand, + passiveTestHomeFlag, + home, + "--context", + "chosen", + passiveTestProviderFlag, + "fixture-provider", + }, + ) + err := root.Execute() + if state == passiveRunError { + require.ErrorIs(t, err, wantErr) + } else { + require.NoError(t, err) + } + require.True(t, called) + }) + } +} + +func mustPassiveDataDir(t *testing.T, paths config.PathManager) string { + t.Helper() + data, err := paths.DataDir() + require.NoError(t, err) + return data +} + +func writePassiveConfig(t *testing.T, path string) { + t.Helper() + require.NoError( + t, + os.WriteFile( + path, + []byte("contexts:\n chosen:\n options:\n LOG_LEVEL:\n value: debug\n"), + 0o600, + ), + ) +} + +func TestPassiveRootPreparationErrors(t *testing.T) { + states := []string{ + "malformed config", + "pending deletion", + passiveInvalidDeletion, + passiveExternalDeletion, + } + for _, state := range states { + t.Run(state, func(t *testing.T) { + rootDir, home := passiveFixtureEnvironment(t) + require.NoError(t, os.MkdirAll(home, 0o700)) + path := filepath.Join(home, config.ConfigFile) + if state == passiveExternalDeletion { + path = filepath.Join(rootDir, "external.yaml") + t.Setenv(config.EnvConfig, path) + } + require.NoError(t, os.WriteFile(path, []byte("contexts: ["), 0o600)) + if state != "malformed config" { + writePassiveIntent(t, home, path, state == passiveInvalidDeletion) + } + preservePassiveFixture(t, rootDir) + root, _ := passiveTestRoot(func(*cobra.Command, []string) error { + t.Fatal("RunE reached after preparation failure") + return nil + }) + root.SetArgs([]string{passiveTestCommand, passiveTestHomeFlag, home}) + err := root.Execute() + require.Error(t, err) + switch state { + case "pending deletion", passiveExternalDeletion: + require.ErrorIs(t, err, config.ErrContextDeletionPending) + case passiveInvalidDeletion: + require.ErrorIs(t, err, config.ErrContextDeletionIntentInvalid) + default: + require.Contains(t, err.Error(), "yaml") + } + }) + } +} + +func writePassiveIntent(t *testing.T, home, path string, invalid bool) { + t.Helper() + intent := config.ContextDeletionIntent{ + SchemaVersion: 1, ConfigFile: path, StoreDirectory: filepath.Dir(path), + DataDirectory: home, Context: "chosen", Fingerprint: strings.Repeat("a", 64), + } + raw, err := json.Marshal(intent) + require.NoError(t, err) + if invalid { + raw = []byte(`{"private":"invalid-intent-fixture"`) + } + require.NoError( + t, + os.WriteFile( + filepath.Join(filepath.Dir(path), config.ContextDeletionIntentFile), + raw, + 0o600, + ), + ) +} + +func TestPassiveUnmarkedChildUsesOrdinaryHooks(t *testing.T) { + _, home := passiveFixtureEnvironment(t) + root, _ := passiveTestRoot(func(command *cobra.Command, _ []string) error { + require.Equal(t, home, os.Getenv(config.EnvHome)) + _, ok := flags.PassiveInputsFromContext(command.Context()) + require.False(t, ok) + return nil + }) + root.SetArgs([]string{passiveTestGroup, passiveTestActive, passiveTestHomeFlag, home}) + require.NoError(t, root.Execute()) + _, exists := os.LookupEnv(config.EnvHome) + require.False(t, exists, "ordinary post-run retains its existing Unsetenv behavior") + _, err := os.Stat(home) + require.NoError(t, err) +} + +func TestPassiveSandboxPolicy(t *testing.T) { + require.NoError(t, passiveHostInspection(false)) + require.ErrorContains(t, passiveHostInspection(true), "unsupported inside Flatpak") +} + +func TestPassivePreparseOutput(t *testing.T) { + rootDir, _ := passiveFixtureEnvironment(t) + preservePassiveFixture(t, rootDir) + root, global := passiveTestRoot(nil) + root.SetContext(withInvocationPolicy(context.Background(), true)) + original := os.Args + t.Cleanup(func() { os.Args = original }) + os.Args = []string{config.BinaryName, passiveTestCommand} + configureOutput(root, global, false) + require.Equal(t, log.DefaultLevel, defaultPassiveLevel(t, root, global)) + require.Contains(t, telemetryCollectorType(root), "noop") +} + +func defaultPassiveLevel(t *testing.T, root *cobra.Command, global *flags.GlobalFlags) string { + t.Helper() + returnLevel, err := preparePassive(root, global) + require.NoError(t, err) + return returnLevel +} + +func telemetryCollectorType(command *cobra.Command) string { + return fmt.Sprintf("%T", telemetry.FromContext(command.Context())) +} + +func checkPassivePreparedInputs( + t *testing.T, + command *cobra.Command, + expected passiveExpectedInputs, + wantErr error, +) error { + t.Helper() + inputs, ok := flags.PassiveInputsFromContext(command.Context()) + require.True(t, ok) + path, err := inputs.Paths.ConfigFilePath() + require.NoError(t, err) + require.Equal(t, expected.configPath, path) + require.Equal(t, expected.configPath, inputs.Config.Origin) + require.Equal(t, "chosen", inputs.Config.DefaultContext) + require.Equal( + t, + "fixture-provider", + inputs.Config.Contexts["chosen"].DefaultProvider, + ) + require.Equal(t, expected.home, mustPassiveDataDir(t, inputs.Paths)) + if strings.Contains(expected.state, "config") && expected.state != "missing config" { + require.Equal( + t, + "debug", + inputs.Config.ContextOption(config.ContextOptionLogLevel), + ) + require.True(t, log.DebugEnabled()) + } + if expected.state == passiveRunError { + return wantErr + } + return nil +} + +type passiveExpectedInputs struct { + configPath string + home string + state string +} diff --git a/cmd/root.go b/cmd/root.go index dab59e846e..19d9c295e8 100644 --- a/cmd/root.go +++ b/cmd/root.go @@ -6,7 +6,6 @@ import ( "fmt" "os" "os/exec" - "runtime/debug" "slices" "strings" @@ -15,6 +14,7 @@ import ( cliconfig "github.com/devsy-org/devsy/cmd/config" "github.com/devsy-org/devsy/cmd/container" "github.com/devsy-org/devsy/cmd/context" + "github.com/devsy-org/devsy/cmd/dependency" envcmd "github.com/devsy-org/devsy/cmd/env" "github.com/devsy-org/devsy/cmd/feature" "github.com/devsy-org/devsy/cmd/flags" @@ -43,7 +43,6 @@ import ( "github.com/devsy-org/devsy/pkg/workspace" "github.com/go-logr/logr" "github.com/spf13/cobra" - "github.com/spf13/pflag" "golang.org/x/crypto/ssh" "golang.org/x/term" "k8s.io/klog/v2" @@ -147,28 +146,39 @@ func Execute() { os.Exit(run()) } -func run() (code int) { +func run() int { + return runWithRootFactory(BuildRoot) +} + +func runWithRootFactory(buildRoot func() (*cobra.Command, *flags.GlobalFlags)) (code int) { machineMode := false + inspection := false collector := telemetry.FromContext(gocontext.Background()) // noop until BootstrapCLI defer func() { if r := recover(); r != nil { - log.Errorf("panic: %v\n%s", r, debug.Stack()) - panicErr := clierr.NewPanic(r) + panicErr := invocationPanic(r, inspection) collector.RecordCLI(panicErr) code = exitCodeForError(panicErr, machineMode) } collector.Flush() }() - rootCmd, globalFlags := BuildRoot() - target := resolveTarget(rootCmd) - collector = telemetry.BootstrapCLI(target) - rootCmd.SetContext(telemetry.WithCollector(gocontext.Background(), collector)) + rootCmd, globalFlags := buildRoot() + target, remaining := resolveInvocationCommand(rootCmd, os.Args[1:]) + passive := passiveCommand(target, remaining) + inspection = flags.IsDependencyInspection(target) + invocation := readInspectionInvocation(target, remaining) + if !passive { + collector = telemetry.BootstrapCLI(target) + } + ctx := withInvocationPolicy(gocontext.Background(), passive) + ctx = flags.WithInspectionInvocation(ctx, invocation) + rootCmd.SetContext(telemetry.WithCollector(ctx, collector)) isInternal := topLevelCommand(target) == internalCommand machineMode = configureOutput(rootCmd, globalFlags, isInternal) - if !isInternal { + if !isInternal && !passive { if shouldExit, err := flatpak.ReexecOnHost(); err != nil { collector.RecordCLI(err) return exitCodeForError(err, machineMode) @@ -177,26 +187,27 @@ func run() (code int) { } } - err := rootCmd.Execute() - if devsyConfig, cfgErr := config.LoadConfig( - globalFlags.Context, - globalFlags.Provider, - ); cfgErr == nil { - collector = telemetry.ApplyCLIConfig(devsyConfig, collector) - } - - collector.RecordCLI(err) + collector, err := executeRoot(rootCmd, globalFlags, collector) if err != nil { return exitCodeForError(err, machineMode) } return 0 } -func resolveTarget(rootCmd *cobra.Command) *cobra.Command { - if found, _, err := rootCmd.Find(os.Args[1:]); err == nil && found != nil { - return found +func executeRoot( + root *cobra.Command, globalFlags *flags.GlobalFlags, collector telemetry.CLICollector, +) (telemetry.CLICollector, error) { + err := root.Execute() + if !passiveInvocation(root, nil) { + if snapshot, cfgErr := config.LoadConfig( + globalFlags.Context, + globalFlags.Provider, + ); cfgErr == nil { + collector = telemetry.ApplyCLIConfig(snapshot, collector) + } } - return rootCmd + collector.RecordCLI(err) + return collector, err } func configureOutput( @@ -205,7 +216,8 @@ func configureOutput( isInternal bool, ) bool { logOutput := logOutputFromArgs(os.Args[1:]) - machineMode := isMachineConsumer(logOutput, isInternal) + invocation := flags.InspectionInvocationFromContext(rootCmd.Context()) + machineMode := invocation.JSON || isMachineConsumer(logOutput, isInternal) rootCmd.SilenceErrors = true rootCmd.SilenceUsage = machineMode @@ -217,12 +229,16 @@ func configureOutput( format = logOutputText } } + level := log.DefaultLevel + if !passiveInvocation(rootCmd, nil) { + level = defaultLogLevel(globalFlags) + } log.Init(log.Config{ Verbosity: globalFlags.Verbosity, Quiet: globalFlags.Quiet, Debug: globalFlags.Debug, Level: globalFlags.LogLevel, - DefaultLevel: defaultLogLevel(globalFlags), + DefaultLevel: level, VerbositySet: rootCmd.PersistentFlags().Changed(names.Verbose), Format: format, Redactor: secrets.NewEnvironmentRedactor(os.Environ()), @@ -366,11 +382,11 @@ func BuildRoot() (*cobra.Command, *flags.GlobalFlags) { globalFlags := flags.SetGlobalFlags(persistentFlags) _ = completion.RegisterFlagCompletionFuns(rootCmd, globalFlags) - rootCmd.PersistentPreRunE = func(cobraCmd *cobra.Command, _ []string) error { - return rootPreRun(cobraCmd, globalFlags, persistentFlags) + rootCmd.PersistentPreRunE = func(command *cobra.Command, args []string) error { + return prepareRootCommand(command, args, globalFlags) } - rootCmd.PersistentPostRunE = func(_ *cobra.Command, _ []string) error { - if globalFlags.DevsyHome != "" { + rootCmd.PersistentPostRunE = func(command *cobra.Command, args []string) error { + if !passiveInvocation(command, args) && globalFlags.DevsyHome != "" { _ = os.Unsetenv(config.EnvHome) } return nil @@ -381,12 +397,92 @@ func BuildRoot() (*cobra.Command, *flags.GlobalFlags) { return rootCmd, globalFlags } +func prepareRootCommand( + command *cobra.Command, + args []string, + globalFlags *flags.GlobalFlags, +) (err error) { + defer func() { err = inspectionStartupError(command, err) }() + if flags.IsDependencyInspection(command) { + if err := command.Context().Err(); err != nil { + return err + } + } + + if err := validateLogLevel(globalFlags.LogLevel); err != nil { + return err + } + passive := passiveInvocation(command, args) + level, err := prepareRootConfig(command, globalFlags, passive) + if err != nil { + return err + } + configureCommandOutput(command, globalFlags, level) + if !passive { + applyCommandTelemetry(command, globalFlags) + } + return nil +} + +func prepareRootConfig( + command *cobra.Command, + globalFlags *flags.GlobalFlags, + passive bool, +) (string, error) { + if passive { + return preparePassive(command, globalFlags) + } + if globalFlags.DevsyHome != "" { + _ = os.Setenv(config.EnvHome, globalFlags.DevsyHome) + } + // A crashed deletion must be resumed before using its partially cleaned stores. + // The matching delete command validates and resumes under the config lock. + parent := command.Parent() + isContextDelete := command.Name() == "delete" && parent != nil && parent.Name() == "context" + if !isContextDelete { + if err := config.CheckPendingContextDeletion(); err != nil { + return "", err + } + } + return defaultLogLevel(globalFlags), nil +} + +func configureCommandOutput(command *cobra.Command, globalFlags *flags.GlobalFlags, level string) { + command.SilenceUsage = true + logFormat := globalFlags.LogOutput + if logFormat == "" { + if isMachineConsumer("", topLevelCommand(command) == internalCommand) { + logFormat = logOutputJSON + } else { + logFormat = logOutputText + } + } + log.Init(log.Config{ + Verbosity: globalFlags.Verbosity, Quiet: globalFlags.Quiet, Debug: globalFlags.Debug, + Level: globalFlags.LogLevel, DefaultLevel: level, + VerbositySet: command.Root().PersistentFlags().Changed(names.Verbose), + Format: logFormat, Redactor: secrets.NewEnvironmentRedactor(os.Environ()), + }) + klog.SetLogger(logr.New(log.LogrSink())) +} + +func applyCommandTelemetry(command *cobra.Command, globalFlags *flags.GlobalFlags) { + snapshot, err := config.LoadConfig(globalFlags.Context, globalFlags.Provider) + if err == nil { + current := telemetry.FromContext(command.Context()) + command.SetContext( + telemetry.WithCollector(command.Context(), telemetry.ApplyCLIConfig(snapshot, current)), + ) + } +} + func registerSubcommands(rootCmd *cobra.Command, globalFlags *flags.GlobalFlags) { rootCmd.AddCommand( ci.NewCICmd(globalFlags), cliconfig.NewConfigCmd(globalFlags), container.NewContainerCmd(globalFlags, rootCmd.PersistentPreRunE), context.NewContextCmd(globalFlags), + dependency.NewDependencyCmd(globalFlags), envcmd.NewEnvCmd(globalFlags), feature.NewFeatureCmd(globalFlags), ide.NewIDECmd(globalFlags), @@ -404,66 +500,3 @@ func registerSubcommands(rootCmd *cobra.Command, globalFlags *flags.GlobalFlags) rootCmd.AddCommand(pro.NewPlatformCmd(globalFlags)) } } - -func rootPreRun( - cobraCmd *cobra.Command, - globalFlags *flags.GlobalFlags, - persistentFlags *pflag.FlagSet, -) error { - if err := validateLogLevel(globalFlags.LogLevel); err != nil { - return err - } - if globalFlags.DevsyHome != "" { - _ = os.Setenv(config.EnvHome, globalFlags.DevsyHome) - } - if err := checkPendingContextDeletion(cobraCmd); err != nil { - return err - } - cobraCmd.SilenceUsage = true - - log.Init(log.Config{ - Verbosity: globalFlags.Verbosity, - Quiet: globalFlags.Quiet, - Debug: globalFlags.Debug, - Level: globalFlags.LogLevel, - DefaultLevel: defaultLogLevel(globalFlags), - VerbositySet: persistentFlags.Changed(names.Verbose), - Format: resolveLogFormat(cobraCmd, globalFlags.LogOutput), - Redactor: secrets.NewEnvironmentRedactor(os.Environ()), - }) - klog.SetLogger(logr.New(log.LogrSink())) - - devsyConfig, err := config.LoadConfig(globalFlags.Context, globalFlags.Provider) - if err == nil { - current := telemetry.FromContext(cobraCmd.Context()) - cobraCmd.SetContext(telemetry.WithCollector( - cobraCmd.Context(), - telemetry.ApplyCLIConfig(devsyConfig, current), - )) - } - return nil -} - -// checkPendingContextDeletion blocks commands until a crashed deletion is -// resumed, because its stores are only partially cleaned. It reads only -// recovery metadata; the matching delete command validates and resumes under -// the config lock. -func checkPendingContextDeletion(cobraCmd *cobra.Command) error { - parent := cobraCmd.Parent() - isContextDelete := cobraCmd.Name() == "delete" && parent != nil && - parent.Name() == "context" - if isContextDelete { - return nil - } - return config.CheckPendingContextDeletion() -} - -func resolveLogFormat(cobraCmd *cobra.Command, logFormat string) string { - if logFormat != "" { - return logFormat - } - if isMachineConsumer("", topLevelCommand(cobraCmd) == internalCommand) { - return logOutputJSON - } - return logOutputText -} diff --git a/desktop/src/main/__tests__/ipc-provider-icon.test.ts b/desktop/src/main/__tests__/ipc-provider-icon.test.ts index e44fbcc946..b9d1feaffb 100644 --- a/desktop/src/main/__tests__/ipc-provider-icon.test.ts +++ b/desktop/src/main/__tests__/ipc-provider-icon.test.ts @@ -94,6 +94,59 @@ describe("provider_icon IPC", () => { vi.clearAllMocks() }) + it("restricts dependency inspection to trusted passive inputs", async () => { + const { cli } = setup() + await invoke(trustedEvent, "dependency:inspect", { + tool: "apple-container", + providerName: "dock", + }) + expect(cli.run).toHaveBeenCalledExactlyOnceWith([ + "dependency", + "inspect", + "apple-container", + "--for-provider", + "dock", + "--json", + ]) + await expect( + invoke(foreignEvent, "dependency:inspect", { + tool: "docker", + providerName: "dock", + }), + ).rejects.toThrow() + await expect( + invoke(trustedEvent, "dependency:inspect", { + tool: "../x", + providerName: "dock", + }), + ).rejects.toThrow() + await expect( + invoke(trustedEvent, "dependency:inspect", { + tool: "docker", + providerName: "dock", + argv: ["unsafe"], + }), + ).rejects.toThrow() + }) + + it("returns null when the CLI lacks dependency inspection", async () => { + const { cli } = setup() + cli.run.mockRejectedValueOnce(new Error('unknown command "dependency"')) + await expect( + invoke(trustedEvent, "dependency:inspect", { + tool: "docker", + providerName: "dock", + }), + ).resolves.toBeNull() + cli.run.mockRejectedValueOnce(new Error("provider does not exist")) + await expect( + invoke(trustedEvent, "dependency:inspect", { + tool: "docker", + providerName: "missing", + }), + ).rejects.toThrow("provider does not exist") + }) + it("returns the data URL for a trusted sender", async () => { const { cli } = setup() diff --git a/desktop/src/main/ipc.ts b/desktop/src/main/ipc.ts index cbe962b58a..374e3638f4 100644 --- a/desktop/src/main/ipc.ts +++ b/desktop/src/main/ipc.ts @@ -62,6 +62,20 @@ import { WorkspaceLogError, WorkspaceLogReader } from "./workspace-logs.js" import { normalizeWorkspaceStatus } from "./workspace-status.js" const execFileAsync = promisify(execFile) +const dependencyInspectionTools: Record = { + docker: true, + podman: true, + "apple-container": true, + "kubernetes-config": true, +} +const secretProtectionDescriptions: Record = { + "set-passphrase": "Set a passphrase for all file-backed secrets?", + "change-passphrase": "Change the passphrase for all file-backed secrets?", + "remove-passphrase": + "Remove passphrase protection from all file-backed secrets?", + remember: "Remember the secrets passphrase in your OS keychain?", + forget: "Forget the secrets passphrase stored in your OS keychain?", +} interface SecretIpcFailure { ok: false @@ -76,21 +90,68 @@ type SecretUnlockInput = | SecretIpcFailure | { ok: true; requestId?: string; passphrase?: string; remember: boolean } -const protectionDescriptions: Record = { - "set-passphrase": "Set a passphrase for all file-backed secrets?", - "change-passphrase": "Change the passphrase for all file-backed secrets?", - "remove-passphrase": - "Remove passphrase protection from all file-backed secrets?", - remember: "Remember the secrets passphrase in your OS keychain?", - forget: "Forget the secrets passphrase stored in your OS keychain?", +/** Validate and snapshot renderer input before any asynchronous approval. */ +function validateSecretUnlockInput(args: unknown): SecretUnlockInput { + if (!args || typeof args !== "object") + return { ok: false, message: "Invalid unlock request." } + const input = args as { + requestId?: string + passphrase?: unknown + remember?: unknown + } + const passphrase = input.passphrase + const remember = input.remember === undefined ? false : input.remember + if (typeof remember !== "boolean") + return { ok: false, message: "Invalid remember preference." } + if ( + passphrase !== undefined && + (typeof passphrase !== "string" || !passphrase.trim()) + ) + return { ok: false, message: "Enter a non-empty passphrase." } + return { ok: true, requestId: input.requestId, passphrase, remember } +} + +function parseSecretProtectionInput( + args: unknown, +): + | SecretIpcFailure + | { action: string; newPassphrase?: string; currentPassphrase?: string } { + if (!args || typeof args !== "object") + return { ok: false, message: "Unknown protection action." } + const input = args as { + action?: unknown + newPassphrase?: unknown + currentPassphrase?: unknown + } + if ( + typeof input.action !== "string" || + !Object.hasOwn(secretProtectionDescriptions, input.action) + ) + return { ok: false, message: "Unknown protection action." } + if ( + input.currentPassphrase !== undefined && + typeof input.currentPassphrase !== "string" + ) + return { ok: false, message: "Enter a valid current passphrase." } + if ( + input.newPassphrase !== undefined && + typeof input.newPassphrase !== "string" + ) + return { ok: false, message: "Enter a non-empty passphrase." } + return { + action: input.action, + currentPassphrase: input.currentPassphrase, + newPassphrase: input.newPassphrase, + } } -function protectionFailure( +function secretProtectionFailure( err: unknown, - credentials: Array, -): { ok: false; message: string; cliError?: CLIError } { + currentPassphrase: string | undefined, + newPassphrase: string | undefined, +) { const redact = (value: string) => - credentials.reduce( + [currentPassphrase, newPassphrase].reduce( (text, credential) => credential ? text.replaceAll(credential, "***") : text, value, @@ -118,27 +179,6 @@ function protectionFailure( } } -/** Validate and snapshot renderer input before any asynchronous approval. */ -function validateSecretUnlockInput(args: unknown): SecretUnlockInput { - if (!args || typeof args !== "object") - return { ok: false, message: "Invalid unlock request." } - const input = args as { - requestId?: string - passphrase?: unknown - remember?: unknown - } - const passphrase = input.passphrase - const remember = input.remember === undefined ? false : input.remember - if (typeof remember !== "boolean") - return { ok: false, message: "Invalid remember preference." } - if ( - passphrase !== undefined && - (typeof passphrase !== "string" || !passphrase.trim()) - ) - return { ok: false, message: "Enter a non-empty passphrase." } - return { ok: true, requestId: input.requestId, passphrase, remember } -} - function providerVersionFlags(tag: unknown, required = false): string[] { if (tag === undefined || tag === "") { if (!required) return [] @@ -745,88 +785,57 @@ export function registerIpcHandlers(deps: IpcDependencies): { cli.setSessionPassphrase(value) } - ipcMain.handle( - "secret_protection_action", - async ( - event, - args: { - action: string - newPassphrase?: string - currentPassphrase?: string - }, - ) => { - const win = getMainWindow() - if (!win || !isTrustedSecretIpcSender(event, win, secretDocumentURL)) - return secretRequestDenied - const allowed = [ - "set-passphrase", - "change-passphrase", - "remove-passphrase", - "remember", - "forget", - ] - if (!args || typeof args !== "object" || !allowed.includes(args.action)) - return { ok: false, message: "Unknown protection action." } - const action = args.action - const { newPassphrase, currentPassphrase } = args - if ( - currentPassphrase !== undefined && - typeof currentPassphrase !== "string" - ) - return { ok: false, message: "Enter a valid current passphrase." } - if (newPassphrase !== undefined && typeof newPassphrase !== "string") - return { ok: false, message: "Enter a non-empty passphrase." } - const options: CliInvocationOptions = { - allowUnlockPrompt: false, - ...(currentPassphrase !== undefined - ? { env: { DEVSY_SECRETS_PASSPHRASE: currentPassphrase } } - : {}), + ipcMain.handle("secret_protection_action", async (event, args: unknown) => { + const win = getMainWindow() + if (!win || !isTrustedSecretIpcSender(event, win, secretDocumentURL)) + return secretRequestDenied + const input = parseSecretProtectionInput(args) + if ("ok" in input) return input + const { action, newPassphrase, currentPassphrase } = input + const options: CliInvocationOptions = { + allowUnlockPrompt: false, + ...(currentPassphrase !== undefined + ? { env: { DEVSY_SECRETS_PASSPHRASE: currentPassphrase } } + : {}), + } + const cacheGeneration = secretCacheGeneration + const changesPassphrase = + action === "set-passphrase" || action === "change-passphrase" + try { + const command = ["secret", "protection", action] + if (changesPassphrase) { + if (typeof newPassphrase !== "string" || !newPassphrase.trim()) + return { ok: false, message: "Enter a non-empty passphrase." } } - const cacheGeneration = secretCacheGeneration - const changesPassphrase = [ - "set-passphrase", - "change-passphrase", - ].includes(action) - try { - const command = ["secret", "protection", action] - if (changesPassphrase) { - if (typeof newPassphrase !== "string" || !newPassphrase.trim()) - return { ok: false, message: "Enter a non-empty passphrase." } - } - const confirmation = await dialog.showMessageBox(win, { - type: "warning", - title: "Secret protection", - message: protectionDescriptions[action], - detail: "This changes the shared secret store across all contexts.", - buttons: ["Cancel", "Continue"], - defaultId: 0, - cancelId: 0, - noLink: true, - }) - const approvalFailure = protectionApprovalFailure( - event, - cacheGeneration, - confirmation.response, - ) - if (approvalFailure) return approvalFailure - if (changesPassphrase && typeof newPassphrase === "string") { - await cli.runRawStdin([...command, "--stdin"], newPassphrase, options) - updateProtectedSessionCredential( - event, - cacheGeneration, - newPassphrase, - ) - } else { - await cli.runRaw(command, options) - if (action === "remove-passphrase") - updateProtectedSessionCredential(event, cacheGeneration, undefined) - } - return { ok: true } - } catch (err) { - return protectionFailure(err, [currentPassphrase, newPassphrase]) + const confirmation = await dialog.showMessageBox(win, { + type: "warning", + title: "Secret protection", + message: secretProtectionDescriptions[action], + detail: "This changes the shared secret store across all contexts.", + buttons: ["Cancel", "Continue"], + defaultId: 0, + cancelId: 0, + noLink: true, + }) + const approvalFailure = protectionApprovalFailure( + event, + cacheGeneration, + confirmation.response, + ) + if (approvalFailure) return approvalFailure + if (changesPassphrase && typeof newPassphrase === "string") { + await cli.runRawStdin([...command, "--stdin"], newPassphrase, options) + updateProtectedSessionCredential(event, cacheGeneration, newPassphrase) + } else { + await cli.runRaw(command, options) + if (action === "remove-passphrase") + updateProtectedSessionCredential(event, cacheGeneration, undefined) } - }, - ) + return { ok: true } + } catch (err) { + return secretProtectionFailure(err, currentPassphrase, newPassphrase) + } + }) const tunnelProcesses = new Map< string, import("node:child_process").ChildProcess @@ -1257,6 +1266,44 @@ export function registerIpcHandlers(deps: IpcDependencies): { return state.providerList() }) + ipcMain.handle("dependency:inspect", async (event, args: unknown) => { + if (!isTrustedSecretIpcSender(event, getMainWindow(), secretDocumentURL)) + throw new Error( + "Dependency inspection requires the main application window.", + ) + if (!args || typeof args !== "object" || Array.isArray(args)) + throw new Error("Invalid dependency inspection request.") + const input = args as { tool?: unknown; providerName?: unknown } + if (Object.keys(input).sort().join(",") !== "providerName,tool") + throw new Error("Invalid dependency inspection request.") + if ( + typeof input.tool !== "string" || + !Object.hasOwn(dependencyInspectionTools, input.tool) || + typeof input.providerName !== "string" || + !/^[a-z0-9-]{1,32}$/.test(input.providerName) + ) + throw new Error("Invalid dependency inspection request.") + try { + return await cli.run([ + "dependency", + "inspect", + input.tool, + "--for-provider", + input.providerName, + "--json", + ]) + } catch (error) { + const message = error instanceof Error ? error.message : String(error) + if ( + /unknown command\s+["']?dependency["']?|unknown flag\s+["']?--json["']?/i.test( + message, + ) + ) + return null + throw error + } + }) + // Installed-asset reader only: the renderer names a provider and theme, never // a URL or path. Same top-level-document sender policy as secret IPC. ipcMain.handle("provider_icon", async (event, args: ProviderIconRequest) => { diff --git a/desktop/src/renderer/src/lib/components/provider/ProviderSheet.svelte b/desktop/src/renderer/src/lib/components/provider/ProviderSheet.svelte index de7162b989..e8ba65bb93 100644 --- a/desktop/src/renderer/src/lib/components/provider/ProviderSheet.svelte +++ b/desktop/src/renderer/src/lib/components/provider/ProviderSheet.svelte @@ -18,6 +18,7 @@ import UpdateConfirmDialog from "./UpdateConfirmDialog.svelte" import type { CLIError } from "$shared/cli-error.js" import { providerUse, + dependencyInspect, providerUpdateStreaming, providerDelete, providerInit, @@ -44,7 +45,10 @@ import { providerOptionEnumHasValue, } from "$lib/utils/provider-option-enum.js" import { isCommandSuccess } from "$lib/utils/log-parser.js" -import { providerSourceReference } from "$lib/utils/provider-source.js" +import { + dependencyToolForBuiltin, + providerSourceReference, +} from "$lib/utils/provider-source.js" import { providerStatus } from "$lib/utils/provider-status.js" import type { CommandProgress, @@ -63,6 +67,8 @@ let { } = $props() let options = $state>({}) +let dependencyStatus = $state(null) +let dependencyStatusError = $state("") let optionValues = $state>({}) let initialValues = $state>({}) let saving = $state(false) @@ -246,6 +252,8 @@ async function loadOptions() { const request = ++optionsRequest loading = true optionsError = "" + dependencyStatus = null + dependencyStatusError = "" options = {} optionValues = {} initialValues = {} @@ -253,6 +261,9 @@ async function loadOptions() { const raw = await providerOptions(name) if (request !== optionsRequest || provider.name !== name || !open) return options = raw as unknown as Record + const dependencyTool = dependencyToolForBuiltin(provider.source) + if (dependencyTool) + void inspectSheetDependency(dependencyTool, name, request) const values: Record = {} for (const [key, opt] of Object.entries(options)) { @@ -270,6 +281,21 @@ async function loadOptions() { } } +async function inspectSheetDependency( + tool: string, + name: string, + request: number, +): Promise { + try { + const report = await dependencyInspect(tool, name) + if (request !== optionsRequest || provider.name !== name || !open) return + dependencyStatus = report + } catch (inspectionError) { + if (request !== optionsRequest || provider.name !== name || !open) return + dependencyStatusError = `Could not inspect this dependency: ${extractErrorMessage(inspectionError)}` + } +} + $effect(() => { if ( singleMachineOverride !== undefined && @@ -287,8 +313,17 @@ $effect(() => { loadedFor = null return } - if (loadedFor !== provider.name) { - loadedFor = provider.name + const source = provider.source + const identity = [ + provider.name, + provider.version, + source?.raw, + source?.github, + source?.file, + source?.url, + ].join("\0") + if (loadedFor !== identity) { + loadedFor = identity optionSearch = "" loadOptions() loadVersionsFor(provider.name).catch(() => {}) @@ -541,6 +576,7 @@ async function handleSaveOptions() { providers.set(updated) initialValues = { ...optionValues } toasts.success("Options saved") + void loadOptions() } catch (err) { toasts.error(`Failed to save options: ${extractErrorMessage(err)}`) } finally { @@ -631,6 +667,25 @@ async function handleSaveOptions() { {/if} + {#if dependencyStatus !== null || dependencyStatusError} +
+

Passive dependency status

+ {#if dependencyStatusError} +

{dependencyStatusError}

+ {:else} + {@const report = dependencyStatus as { schema?: unknown; schemaVersion?: unknown; surveyMode?: unknown; executed?: unknown; availability?: unknown; reasonCode?: unknown; message?: unknown }} + {#if report.schema === "devsy.dependencies.report.v1" && report.schemaVersion === 1 && report.surveyMode === "passive" && report.executed === false && typeof report.availability === "string" && typeof report.reasonCode === "string" && typeof report.message === "string"} +

Observed availability: {report.availability}

+

{report.message}

+ {#if report.availability === "missing" || report.availability === "incomplete" || report.reasonCode === "dependency_path_invalid"} +

Review dependency requirements outside Devsy.

+ {/if} + {:else} +

Dependency status could not be interpreted safely. Review it outside Devsy.

+ {/if} + {/if} +
+ {/if}
diff --git a/desktop/src/renderer/src/lib/components/provider/ProviderSheet.test.ts b/desktop/src/renderer/src/lib/components/provider/ProviderSheet.test.ts index a03259b8fb..3cdde60d22 100644 --- a/desktop/src/renderer/src/lib/components/provider/ProviderSheet.test.ts +++ b/desktop/src/renderer/src/lib/components/provider/ProviderSheet.test.ts @@ -14,6 +14,7 @@ type ProviderVersionsState = typeof providerVersionsStore extends Readable ? State : never const providerOptions = vi.fn() +const dependencyInspect = vi.fn() const providerUse = vi.fn() const providerUpdateStreaming = vi.fn() const providerDelete = vi.fn() @@ -40,6 +41,7 @@ const providerVersionsBox = vi.hoisted(() => ({ let progressCallback: ((progress: CommandProgress) => void) | null = null vi.mock("$lib/ipc/commands.js", () => ({ + dependencyInspect: (...args: unknown[]) => dependencyInspect(...args), providerOptions: (...args: unknown[]) => providerOptions(...args), providerUse: (...args: unknown[]) => providerUse(...args), providerUpdateStreaming: (...args: unknown[]) => @@ -163,6 +165,7 @@ describe("ProviderSheet", () => { }, })) providerOptions.mockReset() + dependencyInspect.mockReset().mockResolvedValue(null) providerOptions.mockImplementation(async (name: string) => { await new Promise((r) => setTimeout(r, MOCK_IPC_DELAY_MS)) return { @@ -204,6 +207,85 @@ describe("ProviderSheet", () => { unmount() }) + it("keeps the options form usable while passive inspection is pending", async () => { + const inspection = deferred() + dependencyInspect.mockReturnValueOnce(inspection.promise) + const { unmount } = render(ProviderSheet, { + props: { + provider: makeProvider("docker", { source: { raw: "docker" } }), + open: true, + }, + }) + + expect(await screen.findByRole("textbox", { name: "Token" })).toBeDefined() + expect(dependencyInspect).toHaveBeenCalledOnce() + inspection.resolve(null) + unmount() + }) + + it("shows missing passive dependency status and tolerates unavailable inspection", async () => { + dependencyInspect + .mockResolvedValueOnce({ + schema: "devsy.dependencies.report.v1", + schemaVersion: 1, + surveyMode: "passive", + executed: false, + availability: "missing", + compatibility: "unknown", + reasonCode: "dependency_missing", + message: + "Passive inspection does not establish executable identity, version, compatibility, or readiness.", + }) + .mockResolvedValueOnce(null) + const first = render(ProviderSheet, { + props: { + provider: makeProvider("renamed-docker", { source: { raw: "docker" } }), + open: true, + }, + }) + await flushAsync() + expect( + screen.getByText( + "Passive inspection does not establish executable identity, version, compatibility, or readiness.", + ), + ).toBeDefined() + expect( + screen.getByText("Review dependency requirements outside Devsy."), + ).toBeDefined() + expect(dependencyInspect).toHaveBeenCalledWith("docker", "renamed-docker") + first.unmount() + + const second = render(ProviderSheet, { + props: { + provider: makeProvider("podman", { source: { raw: "podman" } }), + open: true, + }, + }) + await flushAsync() + expect( + screen.queryByText(/unavailable in this Devsy CLI version/), + ).toBeNull() + second.unmount() + + const external = render(ProviderSheet, { + props: { + provider: makeProvider("docker", { + source: { + raw: "docker", + github: "github.com/example/other-provider", + }, + }), + open: true, + }, + }) + await flushAsync() + expect(dependencyInspect).toHaveBeenCalledTimes(2) + expect( + screen.queryByRole("region", { name: "Dependency status" }), + ).toBeNull() + external.unmount() + }) + it("uses manifest groups and keeps searched edits without exposing hidden fields", async () => { providerOptions.mockResolvedValue({ HOST: { @@ -937,6 +1019,38 @@ describe("ProviderSheet", () => { unmount() }) + it("clears a built-in dependency report when its source changes under the same name", async () => { + dependencyInspect.mockResolvedValue({ + schema: "devsy.dependencies.report.v1", + schemaVersion: 1, + surveyMode: "passive", + executed: false, + availability: "missing", + reasonCode: "dependency_missing", + message: "Dependency is missing.", + }) + const { rerender, unmount } = render(ProviderSheet, { + props: { + provider: makeProvider("docker", { source: { raw: "docker" } }), + open: true, + }, + }) + await flushAsync() + expect(screen.getByText("Dependency is missing.")).toBeDefined() + + await rerender({ + provider: makeProvider("docker", { + source: { github: "github.com/example/provider", raw: "docker" }, + }), + open: true, + }) + await flushAsync() + expect(screen.queryByText("Dependency is missing.")).toBeNull() + expect(providerOptions).toHaveBeenCalledTimes(2) + expect(dependencyInspect).toHaveBeenCalledOnce() + unmount() + }) + it("does refetch when provider.name actually changes", async () => { const { rerender, unmount } = render(ProviderSheet, { props: { provider: makeProvider("ssh"), open: true }, diff --git a/desktop/src/renderer/src/lib/components/provider/ProviderWizard.svelte b/desktop/src/renderer/src/lib/components/provider/ProviderWizard.svelte index b23505da7d..f0ec5a9fad 100644 --- a/desktop/src/renderer/src/lib/components/provider/ProviderWizard.svelte +++ b/desktop/src/renderer/src/lib/components/provider/ProviderWizard.svelte @@ -17,6 +17,7 @@ import ErrorCard from "$lib/components/ErrorCard.svelte" import type { CLIError } from "$shared/cli-error.js" import { providerAdd, + dependencyInspect, providerAvailable, providerInitStreaming, providerList, @@ -29,6 +30,7 @@ import { providers } from "$lib/stores/providers.js" import { toasts } from "$lib/stores/toasts.js" import { extractErrorMessage } from "$lib/utils/error.js" import { isCommandSuccess } from "$lib/utils/log-parser.js" +import { dependencyToolForBuiltin } from "$lib/utils/provider-source.js" import { initialProviderOptionValue, normalizeProviderOptionEnums, @@ -148,6 +150,9 @@ let installedProvider = $derived( $providers.find((p) => p.name === providerName), ) let options = $state>({}) +let dependencyReport = $state(null) +let dependencyNeedsGuidance = $state(false) +let dependencyGuidance = $state("") let optionValues = $state>({}) let editedOptionKeys = $state>({}) let loadingOptions = $state(false) @@ -248,6 +253,9 @@ function reset() { adding = false providerName = "" options = {} + dependencyReport = null + dependencyNeedsGuidance = false + dependencyGuidance = "" optionValues = {} editedOptionKeys = {} loadingOptions = false @@ -326,24 +334,30 @@ function nameExists(name: string): boolean { return get(providers).some((p) => p.name === name) } -async function handleSelect() { - const operationSession = activeSession - const src = source.trim() +function selectedInstallationName(src: string): string | undefined { if (!src) { error = "Provider source is required" - return + return undefined } if (needsCustomName && !customName.trim()) { error = "Enter an installation name for this custom source." - return + return undefined } const name = customName.trim() || src - const providerSource = - selectedProviderOption && name === src ? undefined : src if (nameExists(name)) { error = `Provider "${name}" already exists. Choose a different name.` - return + return undefined } + return name +} + +async function handleSelect() { + const operationSession = activeSession + const src = source.trim() + const name = selectedInstallationName(src) + if (name === undefined) return + const providerSource = + selectedProviderOption && name === src ? undefined : src error = "" adding = true @@ -370,15 +384,66 @@ async function handleSelect() { const loaded = await loadProviderOptions(operationSession) if (!isCurrentSession(operationSession)) return + await inspectWizardDependency(src, operationSession) + if (!isCurrentSession(operationSession)) return adding = false currentStep = "configure" if (!loaded) return - if (visibleOptions.length === 0) { + if (visibleOptions.length === 0 && !dependencyNeedsGuidance) { currentStep = "initialize" void startInit(operationSession) } } +async function inspectWizardDependency( + providerSource: string, + session: SetupSession, +): Promise { + const tool = dependencyToolForBuiltin(providerSource) + if (!tool) return + try { + const report = await dependencyInspect(tool, session.providerName) + if (!isCurrentSession(session)) return + dependencyReport = report + dependencyNeedsGuidance = false + dependencyGuidance = "" + if (report === null) return + const value = report as { + schema?: unknown + schemaVersion?: unknown + surveyMode?: unknown + executed?: unknown + availability?: unknown + reasonCode?: unknown + message?: unknown + } + const valid = + value.schema === "devsy.dependencies.report.v1" && + value.schemaVersion === 1 && + value.surveyMode === "passive" && + value.executed === false && + typeof value.availability === "string" && + typeof value.reasonCode === "string" && + typeof value.message === "string" + dependencyNeedsGuidance = + !valid || + value.availability === "missing" || + value.availability === "incomplete" || + value.reasonCode === "dependency_path_invalid" || + value.reasonCode === "dependency_platform_unsupported" + if (dependencyNeedsGuidance) { + dependencyGuidance = valid + ? "Check the saved tool path or configuration outside Devsy, then retry inspection." + : "Dependency status could not be interpreted safely." + } + } catch (inspectionError) { + if (!isCurrentSession(session)) return + dependencyReport = null + dependencyNeedsGuidance = true + dependencyGuidance = `Could not inspect the provider dependency: ${extractErrorMessage(inspectionError)}` + } +} + async function loadProviderOptions( operationSession = activeSession, ): Promise { @@ -415,6 +480,7 @@ async function retryLoadProviderOptions() { async function handleConfigure() { const operationSession = activeSession if (!optionsLoaded) return + if (dependencyNeedsGuidance && visibleOptions.length === 0) return if (visibleOptions.length === 0) { error = "" currentStep = "initialize" @@ -448,6 +514,12 @@ async function handleConfigure() { return } if (!isCurrentSession(operationSession)) return + await inspectWizardDependency(source.trim(), operationSession) + if (!isCurrentSession(operationSession)) return + if (dependencyNeedsGuidance) { + saving = false + return + } saving = false currentStep = "initialize" void startInit(operationSession) @@ -697,6 +769,18 @@ function handleDone() {
{:else} + {#if dependencyReport !== null || dependencyNeedsGuidance} +
+

Passive dependency status

+ {#if dependencyReport !== null} +
{JSON.stringify(dependencyReport, null, 2)}
+ {/if} + {#if dependencyNeedsGuidance}

{dependencyGuidance}

{/if} + {#if dependencyNeedsGuidance && dependencyToolForBuiltin(source.trim())} + + {/if} +
+ {/if} {#if !optionsLoaded} {:else if currentStep === "configure"} - {:else if currentStep === "initialize"} diff --git a/desktop/src/renderer/src/lib/components/provider/ProviderWizard.test.ts b/desktop/src/renderer/src/lib/components/provider/ProviderWizard.test.ts index 37f77e5fa5..906f8d77b2 100644 --- a/desktop/src/renderer/src/lib/components/provider/ProviderWizard.test.ts +++ b/desktop/src/renderer/src/lib/components/provider/ProviderWizard.test.ts @@ -12,6 +12,7 @@ import type { Provider, ProviderOption } from "$lib/types/index.js" const { providerAdd, + dependencyInspect, providerAvailable, providerInitStreaming, providerList, @@ -22,6 +23,7 @@ const { onCommandProgress, } = vi.hoisted(() => ({ providerAdd: vi.fn(), + dependencyInspect: vi.fn(), providerAvailable: vi.fn(), providerInitStreaming: vi.fn(), providerList: vi.fn(), @@ -34,6 +36,7 @@ const { vi.mock("$lib/ipc/commands.js", () => ({ providerAdd, + dependencyInspect, providerAvailable, providerInitStreaming, providerList, @@ -79,6 +82,7 @@ describe("ProviderWizard", () => { vi.clearAllMocks() providers.set([]) providerAdd.mockResolvedValue(undefined) + dependencyInspect.mockResolvedValue(null) providerAvailable.mockResolvedValue([]) providerInitStreaming.mockResolvedValue("init-command") providerOptions.mockResolvedValue({}) @@ -381,6 +385,107 @@ describe("ProviderWizard", () => { page.unmount() }) + it("saves a corrected visible tool path before retrying inspection and init", async () => { + providerOptions.mockResolvedValue({ + DOCKER_PATH: { name: "DOCKER_PATH", default: "docker" }, + }) + dependencyInspect + .mockResolvedValueOnce({ + schema: "devsy.dependencies.report.v1", + schemaVersion: 1, + surveyMode: "passive", + executed: false, + availability: "missing", + reasonCode: "dependency_missing", + message: "Passive inspection does not establish readiness.", + }) + .mockResolvedValueOnce({ + schema: "devsy.dependencies.report.v1", + schemaVersion: 1, + surveyMode: "passive", + executed: false, + availability: "unknown", + reasonCode: "dependency_policy_blocked", + message: "Passive inspection does not establish readiness.", + }) + const page = renderWizard() + await fireEvent.click( + screen.getByRole("button", { name: /docker Local Docker/ }), + ) + await fireEvent.click(screen.getByRole("button", { name: "Continue" })) + await fireEvent.input( + await screen.findByRole("textbox", { name: "DOCKER_PATH" }), + { target: { value: "/opt/docker/bin/docker" } }, + ) + await fireEvent.click(screen.getByRole("button", { name: "Continue" })) + await waitFor(() => { + expect(providerSetOptions).toHaveBeenCalledExactlyOnceWith( + "docker", + { DOCKER_PATH: "/opt/docker/bin/docker" }, + false, + ) + expect(dependencyInspect).toHaveBeenCalledTimes(2) + expect(providerInitStreaming).toHaveBeenCalledExactlyOnceWith("docker") + }) + expect(providerSetOptions.mock.invocationCallOrder[0]).toBeLessThan( + dependencyInspect.mock.invocationCallOrder[1], + ) + page.unmount() + }) + + it("blocks init on a missing dependency and allows a retry after external setup", async () => { + providerOptions.mockResolvedValue({}) + dependencyInspect + .mockResolvedValueOnce({ + schema: "devsy.dependencies.report.v1", + schemaVersion: 1, + surveyMode: "passive", + executed: false, + availability: "missing", + reasonCode: "dependency_missing", + message: "Passive inspection does not establish readiness.", + }) + .mockResolvedValueOnce({ + schema: "devsy.dependencies.report.v1", + schemaVersion: 1, + surveyMode: "passive", + executed: false, + availability: "unknown", + reasonCode: "dependency_policy_blocked", + message: "Passive inspection does not establish readiness.", + }) + const page = renderWizard() + await fireEvent.click( + screen.getByRole("button", { name: /docker Local Docker/ }), + ) + await fireEvent.click(screen.getByRole("button", { name: "Continue" })) + + expect( + await screen.findByText( + "Check the saved tool path or configuration outside Devsy, then retry inspection.", + ), + ).toBeDefined() + expect(dependencyInspect).toHaveBeenCalledWith("docker", "docker") + expect( + screen.getByRole("heading", { name: "Configure docker" }), + ).toBeDefined() + expect(providerInitStreaming).not.toHaveBeenCalled() + await fireEvent.click( + screen.getByRole("button", { name: "Retry inspection" }), + ) + expect(dependencyInspect).toHaveBeenCalledTimes(2) + await waitFor(() => + expect( + screen + .getByRole("button", { name: "Continue" }) + .hasAttribute("disabled"), + ).toBe(false), + ) + await fireEvent.click(screen.getByRole("button", { name: "Continue" })) + expect(providerInitStreaming).toHaveBeenCalledExactlyOnceWith("docker") + page.unmount() + }) + it("keeps a failed init-start retryable and only reports ready after success", async () => { let progressCallback: | ((progress: { @@ -922,6 +1027,31 @@ describe("ProviderWizard", () => { page.unmount() }) + it("does not let abandoned inspection change a reopened wizard", async () => { + const inspection = deferred() + providerOptions.mockResolvedValue({}) + dependencyInspect.mockReturnValueOnce(inspection.promise) + const page = renderWizard() + await fireEvent.click( + screen.getByRole("button", { name: /docker Local Docker/ }), + ) + await fireEvent.click(screen.getByRole("button", { name: "Continue" })) + await waitFor(() => expect(dependencyInspect).toHaveBeenCalledOnce()) + + await page.rerender({ open: false }) + await page.rerender({ open: true }) + inspection.resolve(null) + + expect( + await screen.findByRole("heading", { name: "Select a Provider" }), + ).toBeDefined() + expect( + screen.queryByRole("heading", { name: "Configure docker" }), + ).toBeNull() + expect(providerInitStreaming).not.toHaveBeenCalled() + page.unmount() + }) + it("releases the installed provider when option loading is pending at unmount", async () => { const options = deferred>() providerOptions.mockReturnValueOnce(options.promise) diff --git a/desktop/src/renderer/src/lib/ipc/commands.ts b/desktop/src/renderer/src/lib/ipc/commands.ts index 63588e7616..c904bd6224 100644 --- a/desktop/src/renderer/src/lib/ipc/commands.ts +++ b/desktop/src/renderer/src/lib/ipc/commands.ts @@ -180,6 +180,13 @@ export async function providerList(): Promise { return invoke("provider_list") } +export async function dependencyInspect( + tool: string, + providerName: string, +): Promise { + return invoke("dependency:inspect", { tool, providerName }) +} + export async function providerIcon( request: ProviderIconRequest, ): Promise { diff --git a/desktop/src/renderer/src/lib/utils/provider-source.ts b/desktop/src/renderer/src/lib/utils/provider-source.ts index 79734081b6..dc4300217a 100644 --- a/desktop/src/renderer/src/lib/utils/provider-source.ts +++ b/desktop/src/renderer/src/lib/utils/provider-source.ts @@ -1,5 +1,27 @@ import type { ProviderSource } from "$lib/types/index.js" +export function dependencyToolForBuiltin( + source: ProviderSource | string | undefined, +): string | undefined { + if ( + typeof source !== "string" && + (source?.github || source?.file || source?.url) + ) + return undefined + const name = typeof source === "string" ? source : source?.raw + switch (name) { + case "docker": + case "podman": + return name + case "apple": + return "apple-container" + case "kubernetes": + return "kubernetes-config" + default: + return undefined + } +} + export function providerSourceReference( source?: ProviderSource, ): string | undefined { diff --git a/hack/ci/suites.yaml b/hack/ci/suites.yaml index cf29fd96d0..05cf6f6348 100644 --- a/hack/ci/suites.yaml +++ b/hack/ci/suites.yaml @@ -26,7 +26,15 @@ unit: description: every package outside test/ and e2e/ directories, with the race detector os: [linux, darwin] discover: true - args: [-race, -short] + args: [-race, -short, '-skip=^Test(PassiveProcessLifecycle|InspectShippedMain)$'] + + - name: cli-process-lifecycle + description: CLI startup and inspection process checks after package race tests + os: [linux, darwin] + packages: [./cmd] + run: '^Test(PassiveProcessLifecycle|InspectShippedMain)$' + require_tests: [TestPassiveProcessLifecycle, TestInspectShippedMain] + args: [-race, -short, -count=1, -p=1, -timeout=10m] - name: agent-bootstrap-busybox description: agent bootstrap script under BusyBox sh diff --git a/internal/dependencytest/guards.go b/internal/dependencytest/guards.go new file mode 100644 index 0000000000..cdcdfdf4c9 --- /dev/null +++ b/internal/dependencytest/guards.go @@ -0,0 +1,199 @@ +package dependencytest + +import ( + "context" + "crypto/sha256" + "errors" + "io" + "io/fs" + "net" + "net/http" + "os" + "path/filepath" + "slices" + "strings" + "sync/atomic" + "testing" + + "github.com/stretchr/testify/require" +) + +func Environment() []string { + env := os.Environ() + slices.Sort(env) + return env +} + +type Entry struct { + Path string + Mode fs.FileMode + Size int64 + Digest [sha256.Size]byte + Link string +} + +func Tree(path string) (entries []Entry, err error) { + info, err := os.Lstat(path) + if err != nil { + return nil, err + } + if !info.IsDir() { + return nil, errors.New("snapshot root must be a directory, not a link") + } + root, err := os.OpenRoot(path) + if err != nil { + return nil, err + } + defer func() { err = errors.Join(err, root.Close()) }() + err = fs.WalkDir(root.FS(), ".", func(path string, _ fs.DirEntry, walkErr error) error { + if walkErr != nil { + return walkErr + } + entry, err := snapshotEntry(root, path) + if err == nil { + entries = append(entries, entry) + } + return err + }) + return entries, err +} + +func snapshotEntry(root *os.Root, path string) (Entry, error) { + info, err := root.Lstat(path) + if err != nil { + return Entry{}, err + } + entry := Entry{Path: path, Mode: info.Mode()} + switch { + case info.Mode().IsRegular(): + entry.Size = info.Size() + file, err := root.Open(path) + if err != nil { + return Entry{}, err + } + digest := sha256.New() + _, readErr := io.Copy(digest, file) + if err := errors.Join(readErr, file.Close()); err != nil { + return Entry{}, err + } + copy(entry.Digest[:], digest.Sum(nil)) + case info.Mode()&os.ModeSymlink != 0: + entry.Size = info.Size() + entry.Link, err = root.Readlink(path) + case info.IsDir(): + default: + err = errors.New("snapshot refuses special files") + } + return entry, err +} + +func Preserve(t testing.TB, root string) { + t.Helper() + env := Environment() + tree, err := Tree(root) + require.NoError(t, err) + t.Cleanup(func() { + if !slices.Equal(env, Environment()) { + t.Error("process environment changed") + } + after, err := Tree(root) + require.NoError(t, err) + require.Equal(t, tree, after, "external tree changed") + }) +} + +type ForbiddenEffects struct { + processes atomic.Int64 + network atomic.Int64 +} + +func (s *ForbiddenEffects) Run(context.Context, string, ...string) error { + s.processes.Add(1) + return errors.New("process execution forbidden") +} + +func (s *ForbiddenEffects) DialContext(context.Context, string, string) (net.Conn, error) { + s.network.Add(1) + return nil, errors.New("network dial forbidden") +} + +func (s *ForbiddenEffects) RoundTrip(*http.Request) (*http.Response, error) { + s.network.Add(1) + return nil, errors.New("HTTP request forbidden") +} + +// Check retains evidence when callers swallow an effect's error. +func (s *ForbiddenEffects) Check() error { + if s.processes.Load() != 0 || s.network.Load() != 0 { + return errors.New("forbidden process or network effect attempted") + } + return nil +} + +type QualificationRoot struct { + path string + root *os.Root +} + +func NewQualificationRoot(t testing.TB) *QualificationRoot { + t.Helper() + path, err := filepath.EvalSymlinks(t.TempDir()) + require.NoError(t, err) + root, err := os.OpenRoot(path) + require.NoError(t, err) + t.Cleanup(func() { require.NoError(t, root.Close()) }) + return &QualificationRoot{path: path, root: root} +} + +func (q *QualificationRoot) Path() string { return q.path } + +func (q *QualificationRoot) Validate(homes ...string) error { + if len(homes) == 0 { + return errors.New("qualification homes required") + } + current, err := os.Lstat(q.path) + if err != nil { + return err + } + allocated, err := q.root.Stat(".") + if err != nil { + return err + } + if !current.IsDir() || !os.SameFile(current, allocated) { + return errors.New("qualification root was replaced") + } + for _, home := range homes { + if err := q.validateHome(home); err != nil { + return err + } + } + return nil +} + +func (q *QualificationRoot) validateHome(home string) error { + // Cleaning first can hide a symlink traversed before a parent component. + if !filepath.IsAbs(home) || filepath.Clean(home) != home { + return errors.New("qualification home must be a clean absolute path") + } + rel, err := filepath.Rel(q.path, home) + if err != nil || rel == "." || !filepath.IsLocal(rel) { + return errors.New("qualification home must be beneath the allocated temporary root") + } + return q.validateDirectories(rel) +} + +func (q *QualificationRoot) validateDirectories(rel string) error { + // Reject links before inspecting their targets, including fake user homes. + path := "" + for component := range strings.SplitSeq(rel, string(filepath.Separator)) { + path = filepath.Join(path, component) + info, err := q.root.Lstat(path) + if err != nil { + return err + } + if !info.IsDir() { + return errors.New("qualification home must contain only directories, without links") + } + } + return nil +} diff --git a/internal/dependencytest/guards_test.go b/internal/dependencytest/guards_test.go new file mode 100644 index 0000000000..aa7519d86f --- /dev/null +++ b/internal/dependencytest/guards_test.go @@ -0,0 +1,170 @@ +package dependencytest + +import ( + "context" + "os" + "path/filepath" + "testing" + + "github.com/stretchr/testify/require" +) + +func TestEnvironmentDetectsMutation(t *testing.T) { + t.Setenv("DEVSY_GUARD_SENTINEL", "before") + before := Environment() + require.Equal(t, before, Environment()) + t.Setenv("DEVSY_GUARD_SENTINEL", "after") + require.NotEqual(t, before, Environment()) +} + +func TestTreeDetectsMutation(t *testing.T) { + mutations := map[string]func(string) error{ + "content": func(path string) error { return os.WriteFile(path, []byte("other"), 0o600) }, + "size": func(path string) error { return os.WriteFile(path, []byte("longer"), 0o600) }, + "path": func(path string) error { return os.Rename(path, path+".renamed") }, + "delete": os.Remove, + "create": func(path string) error { return os.WriteFile(path+".new", nil, 0o600) }, + "mode": func(path string) error { return os.Chmod(path, 0o400) }, + } + for name, mutate := range mutations { + t.Run(name, func(t *testing.T) { + root := t.TempDir() + path := filepath.Join(root, "external") + require.NoError(t, os.WriteFile(path, []byte("bytes"), 0o600)) + before, err := Tree(root) + require.NoError(t, err) + require.NoError(t, mutate(path)) + after, err := Tree(root) + require.NoError(t, err) + require.NotEqual(t, before, after) + }) + } +} + +func TestPreserveAllowsReads(t *testing.T) { + root := t.TempDir() + path := filepath.Join(root, "external") + require.NoError(t, os.WriteFile(path, []byte("bytes"), 0o600)) + Preserve(t, root) + reader, err := os.OpenRoot(root) + require.NoError(t, err) + t.Cleanup(func() { require.NoError(t, reader.Close()) }) + data, err := reader.ReadFile("external") + require.NoError(t, err) + require.Equal(t, "bytes", string(data)) +} + +func TestTreeDoesNotFollowLinks(t *testing.T) { + root, outside := t.TempDir(), t.TempDir() + link := filepath.Join(root, "link") + require.NoError(t, os.Symlink(outside, link)) + before, err := Tree(root) + require.NoError(t, err) + require.Len(t, before, 2) + require.Equal(t, outside, before[1].Link) + require.NoError(t, os.WriteFile(filepath.Join(outside, "unobserved"), []byte("data"), 0o600)) + after, err := Tree(root) + require.NoError(t, err) + require.Equal(t, before, after) + _, err = Tree(link) + require.Error(t, err) + require.NoError(t, os.Remove(link)) + require.NoError(t, os.Symlink(filepath.Join(outside, "missing"), link)) + after, err = Tree(root) + require.NoError(t, err) + require.NotEqual(t, before, after) +} + +func TestForbiddenEffects(t *testing.T) { + for name, attempt := range map[string]func(*ForbiddenEffects) error{ + "process": func(s *ForbiddenEffects) error { return s.Run(context.Background(), "never-run") }, + "dial": func(s *ForbiddenEffects) error { + conn, err := s.DialContext(context.Background(), "tcp", "example.invalid:443") + require.Nil(t, conn) + return err + }, + "http": func(s *ForbiddenEffects) error { + response, err := s.RoundTrip(nil) + require.Nil(t, response) + return err + }, + } { + t.Run(name, func(t *testing.T) { + spy := &ForbiddenEffects{} + require.NoError(t, spy.Check()) + require.Error(t, attempt(spy)) + require.Error(t, spy.Check()) + }) + } +} + +func TestQualificationHomes(t *testing.T) { + q := NewQualificationRoot(t) + devsy, msb := filepath.Join(q.Path(), "devsy"), filepath.Join(q.Path(), "msb") + require.NoError(t, os.Mkdir(devsy, 0o700)) + require.NoError(t, os.Mkdir(msb, 0o700)) + Preserve(t, q.Path()) + require.NoError(t, q.Validate(devsy, msb)) + fakeUserHome := t.TempDir() + Preserve(t, fakeUserHome) + for _, path := range []string{fakeUserHome, q.Path(), "relative", "", q.Path() + "-sibling"} { + require.Error(t, q.Validate(path)) + } + require.Error(t, q.Validate()) + require.Error(t, q.Validate(filepath.Join(q.Path(), "missing"))) + link := filepath.Join(q.Path(), "escape") + require.NoError(t, os.Symlink(fakeUserHome, link)) + t.Cleanup(func() { require.NoError(t, os.Remove(link)) }) + require.Error(t, q.Validate(link)) + require.Error(t, q.Validate(filepath.Join(link, ".microsandbox"))) +} + +func TestQualificationRejectsReplacedRoot(t *testing.T) { + q := NewQualificationRoot(t) + fakeUserHome := t.TempDir() + Preserve(t, fakeUserHome) + require.NoError(t, os.Remove(q.Path())) + require.NoError(t, os.Symlink(fakeUserHome, q.Path())) + require.Error(t, q.Validate(filepath.Join(q.Path(), ".microsandbox"))) +} + +func TestQualificationRejectsUncleanSymlinkPath(t *testing.T) { + q := NewQualificationRoot(t) + fakeOutside := t.TempDir() + localHome := filepath.Join(q.Path(), "home") + outsideHome := filepath.Join(fakeOutside, "home") + nested := filepath.Join(fakeOutside, "nested") + for _, path := range []string{localHome, outsideHome, nested} { + require.NoError(t, os.Mkdir(path, 0o700)) + } + require.NoError(t, os.Symlink(nested, filepath.Join(q.Path(), "escape"))) + Preserve(t, q.Path()) + Preserve(t, fakeOutside) + sep := string(filepath.Separator) + raw := q.Path() + sep + "escape" + sep + ".." + sep + "home" + resolved, err := filepath.EvalSymlinks(raw) + require.NoError(t, err) + canonicalOutside, err := filepath.EvalSymlinks(outsideHome) + require.NoError(t, err) + require.Equal(t, canonicalOutside, resolved) + require.Equal(t, localHome, filepath.Clean(raw)) + require.NoError(t, q.Validate(localHome)) + require.ErrorContains(t, q.Validate(raw), "clean absolute path") +} + +func TestQualificationCleanPaths(t *testing.T) { + q := NewQualificationRoot(t) + home := filepath.Join(q.Path(), "runtime \u03bb", "home") + require.NoError(t, os.MkdirAll(home, 0o700)) + Preserve(t, q.Path()) + require.NoError(t, q.Validate(home)) + sep := string(filepath.Separator) + for _, raw := range []string{ + home + sep, + q.Path() + sep + sep + "runtime \u03bb" + sep + "home", + q.Path() + sep + "." + sep + "runtime \u03bb" + sep + "home", + home + sep + ".." + sep + "home", + } { + require.ErrorContains(t, q.Validate(raw), "clean absolute path") + } +} diff --git a/internal/dependencytest/lockorder.go b/internal/dependencytest/lockorder.go new file mode 100644 index 0000000000..17ea79d3c1 --- /dev/null +++ b/internal/dependencytest/lockorder.go @@ -0,0 +1,103 @@ +package dependencytest + +import ( + "errors" + "fmt" + "slices" +) + +type LockKind string + +const ( + ArtifactLock LockKind = "artifact" + GateLock LockKind = "G" + ConfigLock LockKind = "config" + InitLock LockKind = "init" +) + +type WorkKind string + +const ( + MetadataWork WorkKind = "bounded metadata" + ProcessWork WorkKind = "process" + NetworkWork WorkKind = "network" + PromptWork WorkKind = "prompt" + RuntimeWork WorkKind = "runtime" + WorkspaceWork WorkKind = "workspace" +) + +// LockOrder checks a single test trace's reported events without taking locks. +type LockOrder struct { + held []LockKind +} + +func (s *LockOrder) Acquire(lock LockKind) error { + if slices.Contains(s.held, lock) { + return fmt.Errorf("lock %s already held", lock) + } + switch lock { + case ArtifactLock: + case GateLock: + if err := s.canAcquireGate(); err != nil { + return err + } + case ConfigLock: + if !slices.Contains(s.held, GateLock) { + return errors.New("config requires G") + } + default: + return errors.New( + "only artifact, G and config may use blocking acquisition; init requires TryInit", + ) + } + s.held = append(s.held, lock) + return nil +} + +func (s *LockOrder) TryInit(acquired bool) error { + if slices.Contains(s.held, InitLock) { + return errors.New("init already held") + } + if acquired { + s.held = append(s.held, InitLock) + } + return nil +} + +func (s *LockOrder) Release(lock LockKind) error { + if len(s.held) == 0 || s.held[len(s.held)-1] != lock { + return fmt.Errorf("release %s in reverse acquisition order", lock) + } + s.held = s.held[:len(s.held)-1] + return nil +} + +func (s *LockOrder) Work(work WorkKind) error { + switch work { + case MetadataWork: + if !slices.Contains(s.held, ConfigLock) { + return errors.New("bounded metadata requires G then config") + } + case ProcessWork, NetworkWork, PromptWork, RuntimeWork, WorkspaceWork: + if slices.Contains(s.held, GateLock) || slices.Contains(s.held, ConfigLock) { + return fmt.Errorf("%s forbidden under G/config", work) + } + default: + return fmt.Errorf("unknown work %q", work) + } + return nil +} + +func (s *LockOrder) Check() error { + if len(s.held) != 0 { + return fmt.Errorf("locks still held: %v", s.held) + } + return nil +} + +func (s *LockOrder) canAcquireGate() error { + if slices.Contains(s.held, ArtifactLock) || slices.Contains(s.held, InitLock) { + return errors.New("release artifact and init locks before acquiring G") + } + return nil +} diff --git a/internal/dependencytest/lockorder_test.go b/internal/dependencytest/lockorder_test.go new file mode 100644 index 0000000000..9125d2bd25 --- /dev/null +++ b/internal/dependencytest/lockorder_test.go @@ -0,0 +1,138 @@ +package dependencytest + +import ( + "slices" + "testing" + + "github.com/stretchr/testify/require" +) + +func TestLockOrderAllowsSelection(t *testing.T) { + var order LockOrder + require.NoError(t, order.Check()) + require.NoError(t, order.Acquire(ArtifactLock)) + require.NoError(t, order.Work(NetworkWork)) + require.NoError(t, order.Release(ArtifactLock)) + require.NoError(t, order.Acquire(GateLock)) + require.NoError(t, order.TryInit(true)) + require.NoError(t, order.Acquire(ConfigLock)) + require.NoError(t, order.Work(MetadataWork)) + require.NoError(t, order.Release(ConfigLock)) + require.NoError(t, order.Release(InitLock)) + require.NoError(t, order.Release(GateLock)) + for _, work := range []WorkKind{ProcessWork, NetworkWork, PromptWork, RuntimeWork, WorkspaceWork} { + require.NoError(t, order.Work(work)) + } + require.NoError(t, order.Check()) +} + +func TestLockOrderAllowsRemoval(t *testing.T) { + var order LockOrder + require.NoError(t, order.Acquire(GateLock)) + require.NoError(t, order.Acquire(ArtifactLock)) + require.NoError(t, order.Acquire(ConfigLock)) + require.NoError(t, order.Work(MetadataWork)) + require.NoError(t, order.Release(ConfigLock)) + require.NoError(t, order.Release(ArtifactLock)) + require.NoError(t, order.Release(GateLock)) + require.NoError(t, order.Check()) +} + +func TestLockOrderRejectsAcquisition(t *testing.T) { + for _, tt := range []struct { + name string + held []LockKind + next LockKind + }{ + {name: "artifact before G", held: []LockKind{ArtifactLock}, next: GateLock}, + {name: "init before G", held: []LockKind{InitLock}, next: GateLock}, + {name: "config before G", next: ConfigLock}, + {name: "blocking init", next: InitLock}, + {name: "waiting for init under G", held: []LockKind{GateLock}, next: InitLock}, + {name: "waiting for init under config", held: []LockKind{GateLock, ConfigLock}, next: InitLock}, + {name: "duplicate artifact", held: []LockKind{ArtifactLock}, next: ArtifactLock}, + {name: "duplicate G", held: []LockKind{GateLock}, next: GateLock}, + {name: "duplicate config", held: []LockKind{GateLock, ConfigLock}, next: ConfigLock}, + {name: "unknown lock", next: LockKind("unknown")}, + } { + t.Run(tt.name, func(t *testing.T) { + var order LockOrder + holdLocks(t, &order, tt.held...) + require.Error(t, order.Acquire(tt.next)) + for _, lock := range slices.Backward(tt.held) { + require.NoError(t, order.Release(lock)) + } + require.NoError(t, order.Check()) + }) + } +} + +func TestLockOrderTryInit(t *testing.T) { + for _, held := range [][]LockKind{nil, {GateLock}, {GateLock, ConfigLock}} { + var order LockOrder + holdLocks(t, &order, held...) + require.NoError(t, order.TryInit(false)) + require.Error(t, order.Release(InitLock)) + require.NoError(t, order.TryInit(true)) + require.Error(t, order.TryInit(true)) + require.Error(t, order.TryInit(false)) + require.NoError(t, order.Release(InitLock)) + for _, lock := range slices.Backward(held) { + require.NoError(t, order.Release(lock)) + } + require.NoError(t, order.Check()) + } + var order LockOrder + require.NoError(t, order.TryInit(false)) + require.NoError(t, order.Acquire(GateLock)) + require.NoError(t, order.Release(GateLock)) + require.NoError(t, order.TryInit(true)) + require.Error(t, order.Acquire(GateLock)) + require.NoError(t, order.Release(InitLock)) + require.NoError(t, order.Acquire(GateLock)) + require.NoError(t, order.Release(GateLock)) + require.NoError(t, order.Check()) +} + +func TestLockOrderRequiresReverseRelease(t *testing.T) { + var order LockOrder + require.Error(t, order.Release(GateLock)) + holdLocks(t, &order, GateLock, ConfigLock) + require.Error(t, order.Check()) + require.Error(t, order.Release(GateLock)) + require.NoError(t, order.Release(ConfigLock)) + require.Error(t, order.Check()) + require.NoError(t, order.Release(GateLock)) + require.NoError(t, order.Check()) +} + +func TestLockOrderRejectsForbiddenWork(t *testing.T) { + for _, held := range [][]LockKind{{GateLock}, {GateLock, ConfigLock}} { + var order LockOrder + holdLocks(t, &order, held...) + for _, work := range []WorkKind{ProcessWork, NetworkWork, PromptWork, RuntimeWork, WorkspaceWork} { + require.ErrorContains(t, order.Work(work), "forbidden under G/config") + } + } +} + +func TestLockOrderRequiresMetadataLocks(t *testing.T) { + var order LockOrder + require.Error(t, order.Work(MetadataWork)) + require.NoError(t, order.Acquire(GateLock)) + require.Error(t, order.Work(MetadataWork)) + require.NoError(t, order.Acquire(ConfigLock)) + require.NoError(t, order.Work(MetadataWork)) + require.Error(t, order.Work(WorkKind("unknown"))) +} + +func holdLocks(t *testing.T, order *LockOrder, locks ...LockKind) { + t.Helper() + for _, lock := range locks { + if lock == InitLock { + require.NoError(t, order.TryInit(true)) + } else { + require.NoError(t, order.Acquire(lock)) + } + } +} diff --git a/internal/dependencytest/locks_test.go b/internal/dependencytest/locks_test.go new file mode 100644 index 0000000000..3be9e92099 --- /dev/null +++ b/internal/dependencytest/locks_test.go @@ -0,0 +1,42 @@ +package dependencytest + +import ( + "os" + "path/filepath" + "testing" + + "github.com/gofrs/flock" + "github.com/stretchr/testify/require" +) + +func TestHeldFlockOutranksStalePID(t *testing.T) { + for _, kind := range []string{"operations", "leases"} { + t.Run(kind, func(t *testing.T) { + root := t.TempDir() + metadata := filepath.Join(root, kind+".json") + require.NoError( + t, + os.WriteFile(metadata, []byte(`{"pid":-1,"state":"running"}`), 0o600), + ) + owner, contender := flock.New( + filepath.Join(root, "live.lock"), + ), flock.New( + filepath.Join(root, "live.lock"), + ) + t.Cleanup( + func() { require.NoError(t, owner.Close()); require.NoError(t, contender.Close()) }, + ) + locked, err := owner.TryLock() + require.NoError(t, err) + require.True(t, locked) + locked, err = contender.TryLock() + require.NoError(t, err) + require.False(t, locked) + require.NoError(t, owner.Unlock()) + locked, err = contender.TryLock() + require.NoError(t, err) + require.True(t, locked) + require.FileExists(t, metadata) + }) + } +} diff --git a/pkg/config/config.go b/pkg/config/config.go index 2de0014eba..23e11eb792 100644 --- a/pkg/config/config.go +++ b/pkg/config/config.go @@ -242,7 +242,19 @@ func CloneConfig(config *Config) *Config { } func LoadConfig(contextOverride string, providerOverride string) (*Config, error) { - configOrigin, err := GetConfigPath() + return LoadConfigWithPathManager(DefaultPathManager(), contextOverride, providerOverride) +} + +// LoadConfigWithPathManager loads a config snapshot. Path-resolution effects follow +// pm's policy; use NewReadOnlyPathManager to avoid creating roots during loading. +func LoadConfigWithPathManager( + pm PathManager, + contextOverride, providerOverride string, +) (*Config, error) { + if pm == nil { + return nil, fmt.Errorf("load config: path manager is required") + } + configOrigin, err := pm.ConfigFilePath() if err != nil { return nil, err } @@ -421,7 +433,11 @@ func lockConfigWithDeletionTarget(target string) (func(), error) { // will actually be replaced by an atomic save. A dangling configured symlink // must fail rather than being replaced by a regular file. func getConfigMutationPath() (string, error) { - configPath, err := GetConfigPath() + return getConfigMutationPathWithPathManager(DefaultPathManager()) +} + +func getConfigMutationPathWithPathManager(pm PathManager) (string, error) { + configPath, err := pm.ConfigFilePath() if err != nil { return "", err } diff --git a/pkg/config/config_readonly_test.go b/pkg/config/config_readonly_test.go new file mode 100644 index 0000000000..50e79c3d9c --- /dev/null +++ b/pkg/config/config_readonly_test.go @@ -0,0 +1,210 @@ +package config + +import ( + "errors" + "io/fs" + "os" + "path/filepath" + "testing" + + "github.com/devsy-org/devsy/internal/dependencytest" + "github.com/stretchr/testify/require" +) + +func TestLoadConfigReadOnlyMissing(t *testing.T) { + for _, homeKind := range []string{"platform default", "absolute override", "relative override"} { + t.Run(homeKind, func(t *testing.T) { + root := t.TempDir() + roots := setReadOnlyTestEnvironment(t, root) + t.Chdir(root) + wantOrigin := filepath.Join(roots.config, ConfigFile) + if homeKind != "platform default" { + home := filepath.Join(root, "missing home") + if homeKind == "relative override" { + home = "./missing home" + } + t.Setenv(EnvHome, home) + wantOrigin = filepath.Join(home, ConfigFile) + } + defaultManager := DefaultPathManager() + dependencytest.Preserve(t, root) + for _, overrides := range [][2]string{{"", ""}, {"other", "custom"}} { + loaded, err := LoadConfigWithPathManager( + NewReadOnlyPathManager(), + overrides[0], + overrides[1], + ) + require.NoError(t, err) + wantContext := overrides[0] + if wantContext == "" { + wantContext = DefaultContext + } + require.Equal(t, &Config{ + SchemaVersion: CurrentSchemaVersion, + DefaultContext: wantContext, + Origin: wantOrigin, + Contexts: map[string]*ContextConfig{wantContext: { + DefaultProvider: overrides[1], Providers: map[string]*ProviderConfig{}, + IDEs: map[string]*IDEConfig{}, Options: map[string]OptionValue{}, + }}, + }, loaded) + } + require.Same(t, defaultManager, DefaultPathManager()) + }) + } +} + +func TestLoadConfigReadOnlyNormalization(t *testing.T) { + const changedProvider = "override-provider" + for _, tt := range []struct { + name, payload, context, provider, originalContext, originalProvider string + }{ + {"empty", "{}", "", "", "", ""}, + {"stored defaults", "defaultContext: saved\ncontexts:\n saved:\n defaultProvider: old\n", "", "", "", ""}, + { + "provider override", "defaultContext: saved\ncontexts:\n saved:\n defaultProvider: old\n", + "", changedProvider, "", "old", + }, + { + "both overrides", "defaultContext: saved\ncontexts:\n other:\n defaultProvider: old\n", + "other", changedProvider, "saved", "old", + }, + {"unknown context", "defaultContext: saved\n", "new-context", changedProvider, "saved", ""}, + } { + t.Run(tt.name, func(t *testing.T) { + root := t.TempDir() + setReadOnlyTestEnvironment(t, root) + t.Setenv(EnvHome, root) + path := filepath.Join(root, ConfigFile) + require.NoError(t, os.WriteFile(path, []byte(tt.payload), 0o600)) + dependencytest.Preserve(t, root) + + loaded, err := LoadConfigWithPathManager( + NewReadOnlyPathManager(), + tt.context, + tt.provider, + ) + require.NoError(t, err) + legacy, err := LoadConfig(tt.context, tt.provider) + require.NoError(t, err) + require.Equal(t, legacy, loaded) + require.Equal(t, CurrentSchemaVersion, loaded.SchemaVersion) + require.Equal(t, path, loaded.Origin) + require.Equal(t, tt.originalContext, loaded.OriginalContext) + require.Equal(t, tt.originalProvider, loaded.Current().OriginalProvider) + require.Equal(t, tt.provider != "", loaded.Current().OriginalProviderSet) + require.NotNil(t, loaded.Current().Options) + require.NotNil(t, loaded.Current().Providers) + require.NotNil(t, loaded.Current().IDEs) + if tt.provider != "" { + require.Equal(t, tt.provider, loaded.Current().DefaultProvider) + } + }) + } +} + +func TestLoadConfigReadOnlyConfigOverride(t *testing.T) { + for _, existing := range []bool{false, true} { + t.Run(map[bool]string{false: "missing", true: "existing"}[existing], func(t *testing.T) { + root := t.TempDir() + setReadOnlyTestEnvironment(t, root) + home := filepath.Join(root, "unused home") + t.Setenv(EnvHome, home) + external := filepath.Join(root, "external config.yaml") + t.Setenv(EnvConfig, external) + if existing { + require.NoError( + t, + os.WriteFile( + external, + []byte("schemaVersion: 9\ndefaultContext: outside\n"), + 0o600, + ), + ) + } + dependencytest.Preserve(t, root) + loaded, err := LoadConfigWithPathManager(NewReadOnlyPathManager(), "", "") + require.NoError(t, err) + legacy, err := LoadConfig("", "") + require.NoError(t, err) + require.Equal(t, legacy, loaded) + require.Equal(t, external, loaded.Origin) + if existing { + require.Equal(t, "outside", loaded.DefaultContext) + require.Equal(t, 9, loaded.SchemaVersion) + } + require.NoDirExists(t, home) + }) + } +} + +func TestLoadConfigReadOnlyErrors(t *testing.T) { + const directoryFailure = "directory" + for _, failure := range []string{"malformed", directoryFailure} { + t.Run(failure, func(t *testing.T) { + root := t.TempDir() + setReadOnlyTestEnvironment(t, root) + t.Setenv(EnvHome, root) + path := filepath.Join(root, ConfigFile) + if failure == directoryFailure { + require.NoError(t, os.Mkdir(path, 0o700)) + } else { + require.NoError(t, os.WriteFile(path, []byte("contexts: ["), 0o600)) + } + dependencytest.Preserve(t, root) + loaded, err := LoadConfigWithPathManager(NewReadOnlyPathManager(), "", "") + require.Nil(t, loaded) + require.Error(t, err) + _, legacyErr := LoadConfig("", "") + require.EqualError(t, err, legacyErr.Error()) + if failure == directoryFailure { + var pathErr *os.PathError + require.ErrorAs(t, err, &pathErr) + require.Equal(t, path, pathErr.Path) + require.ErrorContains(t, err, "read config:") + } + }) + } +} + +type failingConfigPathManager struct { + PathManager + err error +} + +func (pm failingConfigPathManager) ConfigFilePath() (string, error) { return "", pm.err } + +func TestLoadConfigReadOnlyManagerFailure(t *testing.T) { + root := t.TempDir() + setReadOnlyTestEnvironment(t, root) + t.Setenv(EnvHome, filepath.Join(root, "must remain absent")) + dependencytest.Preserve(t, root) + wantErr := errors.New("config path unavailable") + loaded, err := LoadConfigWithPathManager(failingConfigPathManager{err: wantErr}, "", "") + require.Nil(t, loaded) + require.ErrorIs(t, err, wantErr) + require.Same(t, wantErr, err) + loaded, err = LoadConfigWithPathManager(nil, "", "") + require.Nil(t, loaded) + require.EqualError(t, err, "load config: path manager is required") +} + +func TestLoadConfigReadOnlyPreservesDefaultManagerPolicy(t *testing.T) { + root := t.TempDir() + setReadOnlyTestEnvironment(t, root) + home := filepath.Join(root, "normal home") + t.Setenv(EnvHome, home) + defaultManager := DefaultPathManager() + t.Run("read only", func(t *testing.T) { + dependencytest.Preserve(t, root) + _, err := LoadConfigWithPathManager(NewReadOnlyPathManager(), "", "") + require.NoError(t, err) + require.Same(t, defaultManager, DefaultPathManager()) + _, err = os.Stat(home) + require.ErrorIs(t, err, fs.ErrNotExist) + }) + _, err := LoadConfig("", "") + require.NoError(t, err) + require.DirExists(t, home) + require.NoFileExists(t, filepath.Join(home, ConfigFile)) +} diff --git a/pkg/config/context_deletion.go b/pkg/config/context_deletion.go index 98462721be..b368077ff9 100644 --- a/pkg/config/context_deletion.go +++ b/pkg/config/context_deletion.go @@ -68,7 +68,16 @@ func (e *ContextDeletionPendingError) Unwrap() error { return ErrContextDeletion // CheckPendingContextDeletion is startup detection only. It does not open a // value store, request credentials, or change any persistent data. func CheckPendingContextDeletion() error { - intent, err := ReadContextDeletionIntent() + return CheckPendingContextDeletionWithPathManager(DefaultPathManager()) +} + +// CheckPendingContextDeletionWithPathManager detects the startup fence using +// only pm for path resolution. Use a read-only manager to avoid creating roots. +func CheckPendingContextDeletionWithPathManager(pm PathManager) error { + if pm == nil { + return ErrContextDeletionIntentInvalid + } + intent, err := readContextDeletionIntentWithPathManager(pm) if err != nil { return err } @@ -88,7 +97,11 @@ func ContextDeletionFingerprint(ctx *ContextConfig) (string, error) { } func ReadContextDeletionIntent() (*ContextDeletionIntent, error) { - path, _, err := contextDeletionPaths() + return readContextDeletionIntentWithPathManager(DefaultPathManager()) +} + +func readContextDeletionIntentWithPathManager(pm PathManager) (*ContextDeletionIntent, error) { + path, _, err := contextDeletionPathsWithPathManager(pm) if err != nil { return nil, ErrContextDeletionIntentInvalid } @@ -99,7 +112,7 @@ func ReadContextDeletionIntent() (*ContextDeletionIntent, error) { if raw == nil { return nil, nil } - return decodeContextDeletionIntent(raw) + return decodeContextDeletionIntent(raw, pm) } func readContextDeletionBytes(path string) ([]byte, error) { @@ -121,7 +134,7 @@ func readContextDeletionBytes(path string) ([]byte, error) { return raw, nil } -func decodeContextDeletionIntent(raw []byte) (*ContextDeletionIntent, error) { +func decodeContextDeletionIntent(raw []byte, pm PathManager) (*ContextDeletionIntent, error) { var intent ContextDeletionIntent decoder := json.NewDecoder(strings.NewReader(string(raw))) decoder.DisallowUnknownFields() @@ -132,7 +145,7 @@ func decodeContextDeletionIntent(raw []byte) (*ContextDeletionIntent, error) { if err := decoder.Decode(&extra); !errors.Is(err, io.EOF) { return nil, ErrContextDeletionIntentInvalid } - if err := validateContextDeletionIntent(&intent); err != nil { + if err := validateContextDeletionIntentWithPathManager(&intent, pm); err != nil { return nil, err } return &intent, nil @@ -245,7 +258,11 @@ func ClearContextDeletionIntent() error { // ContextDeletionDataDirectory binds context-directory cleanup to the original // data root without resolving the final context directory or following its link. func ContextDeletionDataDirectory() (string, error) { - path, err := DefaultPathManager().DataDir() + return contextDeletionDataDirectoryWithPathManager(DefaultPathManager()) +} + +func contextDeletionDataDirectoryWithPathManager(pm PathManager) (string, error) { + path, err := pm.DataDir() if err != nil { return "", err } @@ -263,7 +280,11 @@ func ContextDeletionDataDirectory() (string, error) { // ContextDeletionStoreDirectory identifies the configured managed-value root. // It can differ from the real config file's parent when the file is a symlink. func ContextDeletionStoreDirectory() (string, error) { - path, err := GetConfigPath() + return contextDeletionStoreDirectoryWithPathManager(DefaultPathManager()) +} + +func contextDeletionStoreDirectoryWithPathManager(pm PathManager) (string, error) { + path, err := pm.ConfigFilePath() if err != nil { return "", err } @@ -282,7 +303,11 @@ func ContextDeletionStoreDirectory() (string, error) { } func contextDeletionPaths() (string, string, error) { - path, err := getConfigMutationPath() + return contextDeletionPathsWithPathManager(DefaultPathManager()) +} + +func contextDeletionPathsWithPathManager(pm PathManager) (string, string, error) { + path, err := getConfigMutationPathWithPathManager(pm) if err != nil { return "", "", err } @@ -300,6 +325,13 @@ func contextDeletionPaths() (string, string, error) { } func validateContextDeletionIntent(intent *ContextDeletionIntent) error { + return validateContextDeletionIntentWithPathManager(intent, DefaultPathManager()) +} + +func validateContextDeletionIntentWithPathManager( + intent *ContextDeletionIntent, + pm PathManager, +) error { if intent == nil || intent.SchemaVersion != 1 { return ErrContextDeletionIntentInvalid } @@ -309,7 +341,7 @@ func validateContextDeletionIntent(intent *ContextDeletionIntent) error { if !validDeletionFingerprint(intent.Fingerprint) || !validDeletionNames(intent) { return ErrContextDeletionIntentInvalid } - return validateContextDeletionRoots(intent) + return validateContextDeletionRoots(intent, pm) } func validDeletionFingerprint(fingerprint string) bool { @@ -317,16 +349,16 @@ func validDeletionFingerprint(fingerprint string) bool { return err == nil && len(hash) == sha256.Size } -func validateContextDeletionRoots(intent *ContextDeletionIntent) error { - _, expected, err := contextDeletionPaths() +func validateContextDeletionRoots(intent *ContextDeletionIntent, pm PathManager) error { + _, expected, err := contextDeletionPathsWithPathManager(pm) if err != nil || intent.ConfigFile != expected { return ErrContextDeletionIntentInvalid } - directory, err := ContextDeletionStoreDirectory() + directory, err := contextDeletionStoreDirectoryWithPathManager(pm) if err != nil || intent.StoreDirectory != directory { return ErrContextDeletionIntentInvalid } - dataDirectory, err := ContextDeletionDataDirectory() + dataDirectory, err := contextDeletionDataDirectoryWithPathManager(pm) if err != nil || intent.DataDirectory != dataDirectory { return ErrContextDeletionIntentInvalid } diff --git a/pkg/config/context_deletion_readonly_test.go b/pkg/config/context_deletion_readonly_test.go new file mode 100644 index 0000000000..bb899238b7 --- /dev/null +++ b/pkg/config/context_deletion_readonly_test.go @@ -0,0 +1,271 @@ +package config + +import ( + "encoding/json" + "errors" + "os" + "path/filepath" + "runtime" + "strings" + "testing" + + "github.com/devsy-org/devsy/internal/dependencytest" + "github.com/stretchr/testify/require" +) + +const ( + deletionReadOnlyPrivateFixture = "readonly-private-fixture" + deletionReadOnlyDirectoryAlias = "directory alias" +) + +type deletionReadOnlyTestManager struct { + PathManager + configFile, data string + configErr, dataErr error +} + +func (pm *deletionReadOnlyTestManager) ConfigFilePath() (string, error) { + return pm.configFile, pm.configErr +} + +func (pm *deletionReadOnlyTestManager) DataDir() (string, error) { + return pm.data, pm.dataErr +} + +func deletionReadOnlyFixture( + t *testing.T, +) (string, *deletionReadOnlyTestManager, *ContextDeletionIntent) { + t.Helper() + root, err := filepath.EvalSymlinks(t.TempDir()) + require.NoError(t, err) + setReadOnlyTestEnvironment(t, root) + ambient := filepath.Join(root, "ambient") + t.Setenv(EnvHome, ambient) + t.Setenv(EnvConfig, filepath.Join(ambient, ConfigFile)) + decoy := deletionReadOnlyIntent(filepath.Join(ambient, ConfigFile), ambient) + decoy.Context = "ambient" + writeDeletionReadOnlyFixture(t, decoy) + pm := &deletionReadOnlyTestManager{ + PathManager: NewReadOnlyPathManager(), + configFile: filepath.Join(root, "explicit config", ConfigFile), + data: filepath.Join(root, "explicit data"), + } + intent := deletionReadOnlyIntent(pm.configFile, pm.data) + writeDeletionReadOnlyFixture(t, intent) + return root, pm, intent +} + +func deletionReadOnlyIntent(configFile, data string) *ContextDeletionIntent { + return &ContextDeletionIntent{ + SchemaVersion: 1, ConfigFile: configFile, + StoreDirectory: filepath.Dir(configFile), DataDirectory: data, + Context: "readonly-pending", Fingerprint: strings.Repeat("a", 64), + Secrets: []ContextDeletionSecret{{Name: "TOKEN", Backend: "file"}}, + EnvNames: []string{"PLAIN"}, + } +} + +func writeDeletionReadOnlyFixture(t *testing.T, intent *ContextDeletionIntent) { + t.Helper() + require.NoError(t, os.MkdirAll(intent.DataDirectory, 0o700)) + require.NoError(t, os.MkdirAll(filepath.Dir(intent.ConfigFile), 0o700)) + require.NoError(t, os.WriteFile(intent.ConfigFile, []byte("contexts: {}"), 0o600)) + raw, err := json.Marshal(intent) + require.NoError(t, err) + require.NoError(t, os.WriteFile( + filepath.Join(filepath.Dir(intent.ConfigFile), ContextDeletionIntentFile), raw, 0o600, + )) +} + +func preserveDeletionReadOnlyState(t *testing.T, root string) { + t.Helper() + pm := DefaultPathManager() + dependencytest.Preserve(t, root) + t.Cleanup(func() { require.Same(t, pm, DefaultPathManager()) }) +} + +func requireDeletionReadOnlyPending(t *testing.T, pm PathManager, context string) { + t.Helper() + err := CheckPendingContextDeletionWithPathManager(pm) + require.ErrorIs(t, err, ErrContextDeletionPending) + var pending *ContextDeletionPendingError + require.ErrorAs(t, err, &pending) + require.Equal(t, context, pending.Context) + require.Equal(t, (&ContextDeletionPendingError{Context: context}).Error(), err.Error()) +} + +func TestReadOnlyDeletionFenceAbsentRoots(t *testing.T) { + for _, state := range []string{"missing home", "missing config", "missing intent"} { + t.Run(state, func(t *testing.T) { + root := t.TempDir() + setReadOnlyTestEnvironment(t, root) + home := filepath.Join(root, "devsy") + t.Setenv(EnvHome, home) + if state != "missing home" { + require.NoError(t, os.MkdirAll(home, 0o700)) + } + if state == "missing intent" { + require.NoError( + t, + os.WriteFile(filepath.Join(home, ConfigFile), []byte("{}"), 0o600), + ) + } + preserveDeletionReadOnlyState(t, root) + require.NoError(t, CheckPendingContextDeletionWithPathManager(NewReadOnlyPathManager())) + }) + } +} + +func TestReadOnlyDeletionFenceConfigOutsideHome(t *testing.T) { + root, _, intent := deletionReadOnlyFixture(t) + t.Setenv(EnvHome, intent.DataDirectory) + t.Setenv(EnvConfig, intent.ConfigFile) + pm := NewReadOnlyPathManager() + preserveDeletionReadOnlyState(t, root) + requireDeletionReadOnlyPending(t, pm, intent.Context) +} + +func TestReadOnlyDeletionFenceExplicitManagerIgnoresAmbientRoots(t *testing.T) { + root, pm, intent := deletionReadOnlyFixture(t) + preserveDeletionReadOnlyState(t, root) + requireDeletionReadOnlyPending(t, pm, intent.Context) +} + +func TestReadOnlyDeletionFenceRejectsInvalidMetadata(t *testing.T) { + for _, test := range []struct { + name string + change func(*ContextDeletionIntent) + }{ + {"future schema", func(i *ContextDeletionIntent) { i.SchemaVersion = 2 }}, + {"ambient config", func(i *ContextDeletionIntent) { i.ConfigFile = os.Getenv(EnvConfig) }}, + {"ambient store", func(i *ContextDeletionIntent) { i.StoreDirectory = os.Getenv(EnvHome) }}, + {"ambient data", func(i *ContextDeletionIntent) { i.DataDirectory = os.Getenv(EnvHome) }}, + {"unsafe context", func(i *ContextDeletionIntent) { i.Context = "../readonly-private" }}, + {"fingerprint", func(i *ContextDeletionIntent) { i.Fingerprint = deletionReadOnlyPrivateFixture }}, + {"secret name", func(i *ContextDeletionIntent) { i.Secrets[0].Name = deletionReadOnlyPrivateFixture }}, + {"secret backend", func(i *ContextDeletionIntent) { i.Secrets[0].Backend = deletionReadOnlyPrivateFixture }}, + {"environment name", func(i *ContextDeletionIntent) { i.EnvNames[0] = deletionReadOnlyPrivateFixture }}, + } { + t.Run(test.name, func(t *testing.T) { + root, pm, intent := deletionReadOnlyFixture(t) + test.change(intent) + raw, err := json.Marshal(intent) + require.NoError(t, err) + require.NoError(t, os.WriteFile( + filepath.Join(filepath.Dir(pm.configFile), ContextDeletionIntentFile), raw, 0o600, + )) + preserveDeletionReadOnlyState(t, root) + err = CheckPendingContextDeletionWithPathManager(pm) + require.ErrorIs(t, err, ErrContextDeletionIntentInvalid) + require.EqualError(t, err, ErrContextDeletionIntentInvalid.Error()) + }) + } +} + +func TestReadOnlyDeletionFenceRejectsInvalidJSON(t *testing.T) { + for _, kind := range []string{"corrupt", "trailing", "unknown", "oversize"} { + t.Run(kind, func(t *testing.T) { + root, pm, intent := deletionReadOnlyFixture(t) + raw, err := json.Marshal(intent) + require.NoError(t, err) + switch kind { + case "corrupt": + raw = []byte(`{"redacted":`) + case "trailing": + raw = append(raw, []byte(` {"redacted":true}`)...) + case "unknown": + raw = append([]byte(`{"redacted":true,`), raw[1:]...) + case "oversize": + raw = []byte(strings.Repeat(" ", maxContextDeletionIntentSize+1)) + } + require.NoError(t, os.WriteFile( + filepath.Join(filepath.Dir(pm.configFile), ContextDeletionIntentFile), raw, 0o600, + )) + preserveDeletionReadOnlyState(t, root) + err = CheckPendingContextDeletionWithPathManager(pm) + require.ErrorIs(t, err, ErrContextDeletionIntentInvalid) + require.EqualError(t, err, ErrContextDeletionIntentInvalid.Error()) + }) + } +} + +func TestReadOnlyDeletionFenceRejectsNonregularIntent(t *testing.T) { + for _, kind := range []string{"intent directory", "symlink"} { + t.Run(kind, func(t *testing.T) { + if kind == "symlink" && runtime.GOOS == localContextDeletionTestWindows { + t.Skip("symlink creation depends on Windows privileges") + } + root, pm, _ := deletionReadOnlyFixture(t) + path := filepath.Join(filepath.Dir(pm.configFile), ContextDeletionIntentFile) + target := filepath.Join(root, "preserved intent") + require.NoError(t, os.Rename(path, target)) + if kind == "intent directory" { + require.NoError(t, os.Mkdir(path, 0o700)) + } else { + require.NoError(t, os.Symlink(target, path)) + } + preserveDeletionReadOnlyState(t, root) + require.ErrorIs( + t, + CheckPendingContextDeletionWithPathManager(pm), + ErrContextDeletionIntentInvalid, + ) + }) + } +} + +func TestReadOnlyDeletionFenceConfigAliases(t *testing.T) { + if runtime.GOOS == localContextDeletionTestWindows { + t.Skip("symlink creation depends on Windows privileges") + } + for _, kind := range []string{"file alias", deletionReadOnlyDirectoryAlias, "dangling"} { + t.Run(kind, func(t *testing.T) { + root, pm, intent := deletionReadOnlyFixture(t) + alias := filepath.Join(root, "alias") + switch kind { + case "file alias": + require.NoError(t, os.Symlink(pm.configFile, alias)) + pm.configFile = alias + case deletionReadOnlyDirectoryAlias: + require.NoError(t, os.Symlink(filepath.Dir(pm.configFile), alias)) + pm.configFile = filepath.Join(alias, ConfigFile) + case "dangling": + require.NoError(t, os.Symlink("missing.yaml", alias)) + pm.configFile = alias + } + preserveDeletionReadOnlyState(t, root) + if kind == deletionReadOnlyDirectoryAlias { + requireDeletionReadOnlyPending(t, pm, intent.Context) + } else { + require.ErrorIs( + t, + CheckPendingContextDeletionWithPathManager(pm), + ErrContextDeletionIntentInvalid, + ) + } + }) + } +} + +func TestReadOnlyDeletionFencePathErrorsFailClosed(t *testing.T) { + for _, kind := range []string{"nil", "config", "data", "missing data"} { + t.Run(kind, func(t *testing.T) { + root, pm, _ := deletionReadOnlyFixture(t) + var supplied PathManager = pm + switch kind { + case "nil": + supplied = nil + case "config": + pm.configErr = errors.New(deletionReadOnlyPrivateFixture) + case "data": + pm.dataErr = errors.New(deletionReadOnlyPrivateFixture) + case "missing data": + require.NoError(t, os.Remove(pm.data)) + } + preserveDeletionReadOnlyState(t, root) + err := CheckPendingContextDeletionWithPathManager(supplied) + require.ErrorIs(t, err, ErrContextDeletionIntentInvalid) + require.EqualError(t, err, ErrContextDeletionIntentInvalid.Error()) + }) + } +} diff --git a/pkg/config/pathmanager.go b/pkg/config/pathmanager.go index 281977fe06..d193ad1955 100644 --- a/pkg/config/pathmanager.go +++ b/pkg/config/pathmanager.go @@ -7,34 +7,6 @@ import ( "sync" ) -// ensureDir creates the directory at path (and any parents) if it does not -// already exist. It returns the path unchanged so callers can use it inline: -// -// return ensureDir(filepath.Join(base, RepoName)) -func ensureDir(path string) (string, error) { - // #nosec G703 -- paths are derived from user-controlled env vars (XDG_*) or - // well-known OS defaults; path traversal is not a concern for a CLI tool - // running as the invoking user. - if err := os.MkdirAll(path, 0o700); err != nil { - return "", fmt.Errorf("create directory %s: %w", path, err) - } - - return path, nil -} - -// homeOverrideDir roots sub beneath DEVSY_HOME when set, returning ok=false so -// callers fall through to the OS-native default when it is unset. -func homeOverrideDir(sub ...string) (string, bool, error) { - home := os.Getenv(EnvHome) - if home == "" { - return "", false, nil - } - - dir, err := ensureDir(filepath.Join(append([]string{home}, sub...)...)) - - return dir, true, err -} - // joinUnder returns elems joined beneath the directory produced by parent. // A parent error is returned unchanged. func joinUnder(parent func() (string, error), elems ...string) (string, error) { @@ -74,6 +46,13 @@ type PathManager interface { // binaries (e.g. a git-lfs release fallback) can be installed. SystemBinDir() (string, error) + // Dependency roots are shared across contexts. Resolving them may create + // the parent category roots, but does not create dependency subdirectories. + DependencyToolsDir() (string, error) + DependencyDownloadCacheDir() (string, error) + DependencyStateDir() (string, error) + DependencyLocksDir() (string, error) + // Config paths. ConfigFilePath() (string, error) @@ -119,9 +98,31 @@ type PathManager interface { // basePathManager implements every sub-path method by delegating the top-level // directory resolution to the embedded pm field (the concrete per-OS struct). type basePathManager struct { + pathManagerSettings pm PathManager // self-reference wired after construction } +type pathManagerSettings struct { + readOnly bool + homeOverride string +} + +func (b *basePathManager) DependencyToolsDir() (string, error) { + return joinUnder(b.pm.DataDir, "tools") +} + +func (b *basePathManager) DependencyDownloadCacheDir() (string, error) { + return joinUnder(b.pm.CacheDir, "dependencies") +} + +func (b *basePathManager) DependencyStateDir() (string, error) { + return joinUnder(b.pm.StateDir, "dependencies") +} + +func (b *basePathManager) DependencyLocksDir() (string, error) { + return joinUnder(b.DependencyStateDir, "locks") +} + // --- Config paths --- func (b *basePathManager) ConfigFilePath() (string, error) { @@ -284,6 +285,37 @@ func (b *basePathManager) WorkspaceLogsDir() (string, error) { return joinUnder(b.pm.StateDir, "workspace-logs") } +func (b *basePathManager) ensureDir(path string) (string, error) { + if b.readOnly { + return path, nil + } + + // #nosec G703 -- paths are derived from user-controlled env vars (XDG_*) or + // well-known OS defaults; path traversal is not a concern for a CLI tool + // running as the invoking user. + if err := os.MkdirAll(path, 0o700); err != nil { + return "", fmt.Errorf("create directory %s: %w", path, err) + } + + return path, nil +} + +// homeOverrideDir prefers the instance home over DEVSY_HOME, falling through +// to the OS-native default when both are empty. +func (b *basePathManager) homeOverrideDir(sub ...string) (string, bool, error) { + home := b.homeOverride + if home == "" { + home = os.Getenv(EnvHome) + } + if home == "" { + return "", false, nil + } + + dir, err := b.ensureDir(filepath.Join(append([]string{home}, sub...)...)) + + return dir, true, err +} + // inContext returns elems joined beneath ContextDir(context). func (b *basePathManager) inContext(context string, elems ...string) (string, error) { return joinUnder(func() (string, error) { return b.ContextDir(context) }, elems...) @@ -297,7 +329,21 @@ var ( // NewPathManager returns a new PathManager for the current platform. func NewPathManager() PathManager { - return newPlatformPathManager() + return newPlatformPathManager(pathManagerSettings{}) +} + +// NewReadOnlyPathManager resolves the same paths as NewPathManager without +// creating directories. Returned paths need not exist or be writable. +func NewReadOnlyPathManager() PathManager { + return NewReadOnlyPathManagerForHome("") +} + +// NewReadOnlyPathManagerForHome resolves paths without creating directories. +// A nonempty home overrides DEVSY_HOME; empty uses the environment/native defaults. +// DEVSY_CONFIG still overrides ConfigFilePath, and SystemBinDir remains native. +// Returned paths need not exist or be writable and do not establish confinement. +func NewReadOnlyPathManagerForHome(home string) PathManager { + return newPlatformPathManager(pathManagerSettings{readOnly: true, homeOverride: home}) } // DefaultPathManager returns the process-wide singleton PathManager. diff --git a/pkg/config/pathmanager_darwin.go b/pkg/config/pathmanager_darwin.go index 962b43b32f..1e8a332aeb 100644 --- a/pkg/config/pathmanager_darwin.go +++ b/pkg/config/pathmanager_darwin.go @@ -12,15 +12,15 @@ type darwinPathManager struct { basePathManager } -func newPlatformPathManager() PathManager { - pm := &darwinPathManager{} +func newPlatformPathManager(settings pathManagerSettings) PathManager { + pm := &darwinPathManager{basePathManager: basePathManager{pathManagerSettings: settings}} pm.pm = pm return pm } func (d *darwinPathManager) ConfigDir() (string, error) { - if dir, ok, err := homeOverrideDir(); ok { + if dir, ok, err := d.homeOverrideDir(); ok { return dir, err } @@ -29,11 +29,11 @@ func (d *darwinPathManager) ConfigDir() (string, error) { return "", fmt.Errorf("config dir: %w", err) } - return ensureDir(filepath.Join(home, "."+RepoName)) + return d.ensureDir(filepath.Join(home, "."+RepoName)) } func (d *darwinPathManager) DataDir() (string, error) { - if dir, ok, err := homeOverrideDir(); ok { + if dir, ok, err := d.homeOverrideDir(); ok { return dir, err } @@ -42,11 +42,11 @@ func (d *darwinPathManager) DataDir() (string, error) { return "", fmt.Errorf("data dir: %w", err) } - return ensureDir(filepath.Join(home, "."+RepoName)) + return d.ensureDir(filepath.Join(home, "."+RepoName)) } func (d *darwinPathManager) CacheDir() (string, error) { - if dir, ok, err := homeOverrideDir("cache"); ok { + if dir, ok, err := d.homeOverrideDir("cache"); ok { return dir, err } @@ -55,11 +55,11 @@ func (d *darwinPathManager) CacheDir() (string, error) { return "", fmt.Errorf("cache dir: %w", err) } - return ensureDir(filepath.Join(home, ".cache", RepoName)) + return d.ensureDir(filepath.Join(home, ".cache", RepoName)) } func (d *darwinPathManager) StateDir() (string, error) { - if dir, ok, err := homeOverrideDir("state"); ok { + if dir, ok, err := d.homeOverrideDir("state"); ok { return dir, err } @@ -68,12 +68,12 @@ func (d *darwinPathManager) StateDir() (string, error) { return "", fmt.Errorf("state dir: %w", err) } - return ensureDir(filepath.Join(home, "."+RepoName, "state")) + return d.ensureDir(filepath.Join(home, "."+RepoName, "state")) } // RuntimeDir returns a directory for runtime state, such as sockets and PID files. func (d *darwinPathManager) RuntimeDir() (string, error) { - if dir, ok, err := homeOverrideDir("run"); ok { + if dir, ok, err := d.homeOverrideDir("run"); ok { return dir, err } @@ -82,7 +82,7 @@ func (d *darwinPathManager) RuntimeDir() (string, error) { return "", fmt.Errorf("runtime dir: %w", err) } - dir, err := ensureDir(filepath.Join(home, "."+RepoName, "run")) + dir, err := d.ensureDir(filepath.Join(home, "."+RepoName, "run")) if err != nil { return "", err } diff --git a/pkg/config/pathmanager_darwin_test.go b/pkg/config/pathmanager_darwin_test.go index 76a45ee6f4..f2cef0059a 100644 --- a/pkg/config/pathmanager_darwin_test.go +++ b/pkg/config/pathmanager_darwin_test.go @@ -55,3 +55,18 @@ func TestDarwinConfigFilePath(t *testing.T) { t.Errorf("got %q, want %q", got, want) } } + +func readOnlyPlatformTestRoots(home, _ string) readOnlyTestRoots { + data := filepath.Join(home, "."+RepoName) + return readOnlyTestRoots{ + config: data, + data: data, + cache: filepath.Join(home, ".cache", RepoName), + state: filepath.Join( + data, + "state", + ), + runtime: filepath.Join(data, "run"), + systemBin: "/usr/local/bin", + } +} diff --git a/pkg/config/pathmanager_dependencies_test.go b/pkg/config/pathmanager_dependencies_test.go new file mode 100644 index 0000000000..553a86bcc5 --- /dev/null +++ b/pkg/config/pathmanager_dependencies_test.go @@ -0,0 +1,208 @@ +package config + +import ( + "errors" + "io/fs" + "os" + "path/filepath" + "runtime" + "testing" + + "github.com/stretchr/testify/require" +) + +type dependencyTestRoots struct { + PathManager + data, cache, state string + err error +} + +func (p dependencyTestRoots) DataDir() (string, error) { return p.data, p.err } +func (p dependencyTestRoots) CacheDir() (string, error) { return p.cache, p.err } +func (p dependencyTestRoots) StateDir() (string, error) { return p.state, p.err } + +func TestDependencyPathsUseSharedRoots(t *testing.T) { + root := t.TempDir() + pm := &basePathManager{pm: dependencyTestRoots{ + data: filepath.Join(root, "data"), cache: filepath.Join(root, "cache"), + state: filepath.Join(root, "state"), + }} + + paths := []struct { + name string + fn func() (string, error) + want string + }{ + {"tools", pm.DependencyToolsDir, filepath.Join(root, "data", "tools")}, + {"cache", pm.DependencyDownloadCacheDir, filepath.Join(root, "cache", "dependencies")}, + {"state", pm.DependencyStateDir, filepath.Join(root, "state", "dependencies")}, + {"locks", pm.DependencyLocksDir, filepath.Join(root, "state", "dependencies", "locks")}, + } + for _, tt := range paths { + t.Run(tt.name, func(t *testing.T) { + got, err := tt.fn() + require.NoError(t, err) + require.Equal(t, tt.want, got) + }) + } + entries, err := os.ReadDir(root) + require.NoError(t, err) + require.Empty(t, entries) +} + +func TestDependencyPathsPropagateRootErrors(t *testing.T) { + parentErr := errors.New("root unavailable") + pm := &basePathManager{pm: dependencyTestRoots{err: parentErr}} + for name, fn := range map[string]func() (string, error){ + "tools": pm.DependencyToolsDir, "cache": pm.DependencyDownloadCacheDir, + "state": pm.DependencyStateDir, "locks": pm.DependencyLocksDir, + } { + t.Run(name, func(t *testing.T) { + got, err := fn() + require.ErrorIs(t, err, parentErr) + require.Empty(t, got) + }) + } +} + +func TestDependencyPathsPlatformDefaults(t *testing.T) { + home := t.TempDir() + t.Setenv(EnvHome, "") + t.Setenv("HOME", home) + t.Setenv("USERPROFILE", home) + t.Setenv("APPDATA", filepath.Join(home, "AppData", "Roaming")) + t.Setenv("LOCALAPPDATA", filepath.Join(home, "AppData", "Local")) + + data := filepath.Join(home, "."+RepoName) + cache := filepath.Join(home, ".cache", RepoName) + if runtime.GOOS == "windows" { + data = filepath.Join(home, "AppData", "Local", RepoName) + cache = filepath.Join(data, "cache") + } + assertDependencyPaths(t, NewPathManager(), dependencyTestRoots{ + data: data, cache: cache, state: filepath.Join(data, "state"), + }) +} + +func TestDependencyPathsDevsyHomeIsolation(t *testing.T) { + root := t.TempDir() + t.Setenv("HOME", root) + t.Setenv("USERPROFILE", root) + pm := NewPathManager() + var previous []string + for _, name := range []string{"first home", "second \u65e5\u672c\u8a9e home"} { + t.Run(name, func(t *testing.T) { + home := filepath.Join(root, name) + t.Setenv(EnvHome, home) + assertDependencyPaths(t, pm, dependencyTestRoots{ + data: home, + cache: filepath.Join(home, "cache"), + state: filepath.Join(home, "state"), + }) + paths := dependencyPaths(t, pm) + for _, path := range paths { + require.NotContains(t, previous, path) + } + previous = append(previous, paths...) + }) + } +} + +func assertDependencyPaths(t *testing.T, pm PathManager, roots dependencyTestRoots) { + t.Helper() + paths := dependencyPaths(t, pm) + require.Equal(t, []string{ + filepath.Join(roots.data, "tools"), + filepath.Join(roots.cache, "dependencies"), + filepath.Join( + roots.state, + "dependencies", + ), + filepath.Join(roots.state, "dependencies", "locks"), + }, paths) + for _, path := range paths { + _, err := os.Stat(path) + require.ErrorIs(t, err, fs.ErrNotExist, "dependency leaf must not be created: %s", path) + } + for _, parent := range []string{roots.data, roots.cache, roots.state} { + info, err := os.Stat(parent) + require.NoError(t, err) + require.True(t, info.IsDir(), "existing category accessors ensure their roots") + } +} + +func dependencyPaths(t *testing.T, pm PathManager) []string { + t.Helper() + var paths []string + for _, fn := range []func() (string, error){ + pm.DependencyToolsDir, pm.DependencyDownloadCacheDir, pm.DependencyStateDir, pm.DependencyLocksDir, + } { + path, err := fn() + require.NoError(t, err) + paths = append(paths, path) + } + return paths +} + +func TestDependencyPathsPreserveExternalTreeAndEnvironment(t *testing.T) { + home := t.TempDir() + t.Setenv("HOME", home) + t.Setenv("USERPROFILE", home) + t.Setenv(EnvHome, filepath.Join(home, "devsy")) + external := filepath.Join(home, ".microsandbox") + t.Setenv("MSB_HOME", external) + require.NoError(t, os.MkdirAll(filepath.Join(external, "bin"), 0o700)) + require.NoError( + t, + os.WriteFile(filepath.Join(external, "bin", "msb"), []byte("external executable"), 0o600), + ) + require.NoError( + t, + os.WriteFile(filepath.Join(external, "vm-data"), []byte("external data"), 0o600), + ) + before := dependencyTestTree(t, external) + env := os.Environ() + + pm := NewPathManager() + assertDependencyPaths(t, pm, dependencyTestRoots{ + data: filepath.Join(home, "devsy"), cache: filepath.Join(home, "devsy", "cache"), + state: filepath.Join(home, "devsy", "state"), + }) + + require.Equal(t, before, dependencyTestTree(t, external)) + require.Equal(t, env, os.Environ()) +} + +func dependencyTestTree(t *testing.T, root string) map[string]dependencyTestEntry { + t.Helper() + tree, err := os.OpenRoot(root) + require.NoError(t, err) + defer func() { require.NoError(t, tree.Close()) }() + entries := map[string]dependencyTestEntry{} + err = fs.WalkDir(tree.FS(), ".", func(path string, entry fs.DirEntry, err error) error { + if err != nil { + return err + } + info, err := entry.Info() + require.NoError(t, err) + var content []byte + if !entry.IsDir() { + content, err = tree.ReadFile(path) + require.NoError(t, err) + } + entries[path] = dependencyTestEntry{ + mode: info.Mode(), + size: info.Size(), + content: string(content), + } + return nil + }) + require.NoError(t, err) + return entries +} + +type dependencyTestEntry struct { + mode fs.FileMode + size int64 + content string +} diff --git a/pkg/config/pathmanager_explicit_home_test.go b/pkg/config/pathmanager_explicit_home_test.go new file mode 100644 index 0000000000..494704da10 --- /dev/null +++ b/pkg/config/pathmanager_explicit_home_test.go @@ -0,0 +1,202 @@ +package config + +import ( + "os" + "path/filepath" + "sync" + "testing" + + "github.com/devsy-org/devsy/internal/dependencytest" + "github.com/stretchr/testify/require" +) + +func TestReadOnlyPathManagerExplicitHome(t *testing.T) { + root := t.TempDir() + defaults := setReadOnlyTestEnvironment(t, root) + ambient := filepath.Join(root, "ambient home") + t.Setenv(EnvHome, ambient) + t.Chdir(root) + for _, home := range []string{ + filepath.Join(root, "explicit home"), + root + string(filepath.Separator) + "unused/../lexical home/.", + "./relative home/../\u914d\u7f6e/", + " spaced home ", + } { + t.Run(home, func(t *testing.T) { + dependencytest.Preserve(t, root) + assertReadOnlyPaths( + t, + NewReadOnlyPathManagerForHome(home), + explicitHomeTestRoots(home, defaults.systemBin), + ) + require.NoDirExists(t, home) + require.NoDirExists(t, ambient) + }) + } +} + +func TestReadOnlyPathManagerExplicitHomeFileParent(t *testing.T) { + root := t.TempDir() + defaults := setReadOnlyTestEnvironment(t, root) + t.Setenv(EnvHome, filepath.Join(root, "ambient")) + home := filepath.Join(root, "file parent") + require.NoError(t, os.WriteFile(home, []byte("unchanged"), 0o600)) + dependencytest.Preserve(t, root) + + assertReadOnlyPaths( + t, + NewReadOnlyPathManagerForHome(home), + explicitHomeTestRoots(home, defaults.systemBin), + ) +} + +func TestReadOnlyPathManagerExplicitEmptyHome(t *testing.T) { + for _, ambientOverride := range []bool{false, true} { + t.Run( + map[bool]string{false: "native defaults", true: "ambient home"}[ambientOverride], + func(t *testing.T) { + root := t.TempDir() + want := setReadOnlyTestEnvironment(t, root) + if ambientOverride { + home := filepath.Join(root, "ambient") + t.Setenv(EnvHome, home) + want = explicitHomeTestRoots(home, want.systemBin) + } + dependencytest.Preserve(t, root) + + assertReadOnlyPaths(t, NewReadOnlyPathManagerForHome(""), want) + assertReadOnlyPaths(t, NewReadOnlyPathManager(), want) + }, + ) + } +} + +func TestLoadConfigWithExplicitHome(t *testing.T) { + const externalConfig = "outside config.yaml" + for _, tt := range []struct { + name, override string + existing bool + }{ + {name: "missing home config"}, + {name: "existing home config", existing: true}, + {name: "missing external config", override: externalConfig}, + {name: "existing external config", override: externalConfig, existing: true}, + {name: "relative external config", override: "./unused/../\u914d\u7f6e.yaml"}, + } { + t.Run(tt.name, func(t *testing.T) { + root := t.TempDir() + setReadOnlyTestEnvironment(t, root) + t.Chdir(root) + ambient, home := filepath.Join(root, "ambient"), filepath.Join(root, "explicit") + t.Setenv(EnvHome, ambient) + require.NoError(t, os.MkdirAll(ambient, 0o700)) + ambientConfig := filepath.Join(ambient, ConfigFile) + require.NoError( + t, + os.WriteFile(ambientConfig, []byte("defaultContext: decoy\n"), 0o600), + ) + wantPath := filepath.Join(home, ConfigFile) + if tt.override != "" { + wantPath = tt.override + if tt.override == externalConfig { + wantPath = filepath.Join(root, tt.override) + } + t.Setenv(EnvConfig, wantPath) + } + if tt.existing { + require.NoError(t, os.MkdirAll(filepath.Dir(wantPath), 0o700)) + payload := []byte("schemaVersion: 1\ndefaultContext: selected\n") + require.NoError(t, os.WriteFile(wantPath, payload, 0o600)) + } + defaultManager := DefaultPathManager() + dependencytest.Preserve(t, root) + pm := NewReadOnlyPathManagerForHome(home) + path, err := pm.ConfigFilePath() + require.NoError(t, err) + require.Equal(t, wantPath, path) + loaded, err := LoadConfigWithPathManager(pm, "", "") + require.NoError(t, err) + require.Equal(t, wantPath, loaded.Origin) + require.Equal(t, CurrentSchemaVersion, loaded.SchemaVersion) + wantContext := DefaultContext + if tt.existing { + wantContext = "selected" + } + require.Equal(t, wantContext, loaded.DefaultContext) + require.Same(t, defaultManager, DefaultPathManager()) + }) + } +} + +func TestExplicitHomePathManagerInstanceIsolation(t *testing.T) { + root := t.TempDir() + defaults := setReadOnlyTestEnvironment(t, root) + firstHome, secondHome := filepath.Join(root, "first"), filepath.Join(root, "second") + first := NewReadOnlyPathManagerForHome(firstHome) + second := NewReadOnlyPathManagerForHome(secondHome) + ordinary, readOnly := NewPathManager(), NewReadOnlyPathManager() + empty := NewReadOnlyPathManagerForHome("") + defaultManager := DefaultPathManager() + for _, name := range []string{"ambient one", "ambient two"} { + t.Run(name, func(t *testing.T) { + ambient := filepath.Join(root, name) + t.Setenv(EnvHome, ambient) + ambientRoots := explicitHomeTestRoots(ambient, defaults.systemBin) + assertReadOnlyPaths(t, ordinary, ambientRoots) + dependencytest.Preserve(t, root) + + for range 2 { + assertReadOnlyPaths(t, first, explicitHomeTestRoots(firstHome, defaults.systemBin)) + assertReadOnlyPaths(t, readOnly, ambientRoots) + assertReadOnlyPaths( + t, + second, + explicitHomeTestRoots(secondHome, defaults.systemBin), + ) + assertReadOnlyPaths(t, empty, ambientRoots) + assertReadOnlyPaths(t, defaultManager, ambientRoots) + } + require.Same(t, defaultManager, DefaultPathManager()) + }) + } +} + +func TestExplicitHomePathManagerConcurrentIsolation(t *testing.T) { + root := t.TempDir() + dependencytest.Preserve(t, root) + var workers sync.WaitGroup + for _, name := range []string{"first", "second"} { + home := filepath.Join(root, name) + pm := NewReadOnlyPathManagerForHome(home) + roots := explicitHomeTestRoots(home, "") + paths := append(readOnlyCategoryCases(pm, roots), readOnlyDataCases(pm, roots.data)...) + paths = append(paths, readOnlyOtherCases(pm, roots)...) + for i := range paths { + if paths[i].name == "ConfigFilePath" && os.Getenv(EnvConfig) != "" { + paths[i].want = os.Getenv(EnvConfig) + } + } + for range 10 { + workers.Go(func() { checkConcurrentHomePaths(t, paths) }) + } + } + workers.Wait() +} + +func explicitHomeTestRoots(home, systemBin string) readOnlyTestRoots { + return readOnlyTestRoots{ + config: filepath.Clean(home), data: filepath.Clean(home), + cache: filepath.Join(home, "cache"), state: filepath.Join(home, "state"), + runtime: filepath.Join(home, "run"), systemBin: systemBin, + } +} + +func checkConcurrentHomePaths(t *testing.T, paths []readOnlyPathCase) { + t.Helper() + for _, path := range paths { + got, err := path.fn() + if err != nil || got != path.want { + t.Errorf("%s() = %q, %v; want %q", path.name, got, err, path.want) + } + } +} diff --git a/pkg/config/pathmanager_linux.go b/pkg/config/pathmanager_linux.go index bc6a6e2759..7f7c0cb373 100644 --- a/pkg/config/pathmanager_linux.go +++ b/pkg/config/pathmanager_linux.go @@ -12,15 +12,15 @@ type linuxPathManager struct { basePathManager } -func newPlatformPathManager() PathManager { - pm := &linuxPathManager{} +func newPlatformPathManager(settings pathManagerSettings) PathManager { + pm := &linuxPathManager{basePathManager: basePathManager{pathManagerSettings: settings}} pm.pm = pm return pm } func (l *linuxPathManager) ConfigDir() (string, error) { - if dir, ok, err := homeOverrideDir(); ok { + if dir, ok, err := l.homeOverrideDir(); ok { return dir, err } @@ -29,11 +29,11 @@ func (l *linuxPathManager) ConfigDir() (string, error) { return "", fmt.Errorf("config dir: %w", err) } - return ensureDir(filepath.Join(home, "."+RepoName)) + return l.ensureDir(filepath.Join(home, "."+RepoName)) } func (l *linuxPathManager) DataDir() (string, error) { - if dir, ok, err := homeOverrideDir(); ok { + if dir, ok, err := l.homeOverrideDir(); ok { return dir, err } @@ -42,11 +42,11 @@ func (l *linuxPathManager) DataDir() (string, error) { return "", fmt.Errorf("data dir: %w", err) } - return ensureDir(filepath.Join(home, "."+RepoName)) + return l.ensureDir(filepath.Join(home, "."+RepoName)) } func (l *linuxPathManager) CacheDir() (string, error) { - if dir, ok, err := homeOverrideDir("cache"); ok { + if dir, ok, err := l.homeOverrideDir("cache"); ok { return dir, err } @@ -55,11 +55,11 @@ func (l *linuxPathManager) CacheDir() (string, error) { return "", fmt.Errorf("cache dir: %w", err) } - return ensureDir(filepath.Join(home, ".cache", RepoName)) + return l.ensureDir(filepath.Join(home, ".cache", RepoName)) } func (l *linuxPathManager) StateDir() (string, error) { - if dir, ok, err := homeOverrideDir("state"); ok { + if dir, ok, err := l.homeOverrideDir("state"); ok { return dir, err } @@ -68,15 +68,15 @@ func (l *linuxPathManager) StateDir() (string, error) { return "", fmt.Errorf("state dir: %w", err) } - return ensureDir(filepath.Join(home, "."+RepoName, "state")) + return l.ensureDir(filepath.Join(home, "."+RepoName, "state")) } func (l *linuxPathManager) RuntimeDir() (string, error) { - if dir, ok, err := homeOverrideDir("run"); ok { + if dir, ok, err := l.homeOverrideDir("run"); ok { return dir, err } - return ensureDir(filepath.Join(os.TempDir(), fmt.Sprintf("%s-%d", RepoName, os.Getuid()))) + return l.ensureDir(filepath.Join(os.TempDir(), fmt.Sprintf("%s-%d", RepoName, os.Getuid()))) } func (l *linuxPathManager) SystemBinDir() (string, error) { diff --git a/pkg/config/pathmanager_linux_test.go b/pkg/config/pathmanager_linux_test.go index 18fb4efcb6..2b314f2ec3 100644 --- a/pkg/config/pathmanager_linux_test.go +++ b/pkg/config/pathmanager_linux_test.go @@ -348,3 +348,18 @@ func TestStateSubPaths(t *testing.T) { t.Errorf("got %q, want %q", got, want) } } + +func readOnlyPlatformTestRoots(home, temp string) readOnlyTestRoots { + data := filepath.Join(home, "."+RepoName) + return readOnlyTestRoots{ + config: data, + data: data, + cache: filepath.Join(home, ".cache", RepoName), + state: filepath.Join( + data, + "state", + ), + runtime: filepath.Join(temp, fmt.Sprintf("%s-%d", RepoName, os.Getuid())), + systemBin: "/usr/local/bin", + } +} diff --git a/pkg/config/pathmanager_readonly_test.go b/pkg/config/pathmanager_readonly_test.go new file mode 100644 index 0000000000..b2a9c6f2c6 --- /dev/null +++ b/pkg/config/pathmanager_readonly_test.go @@ -0,0 +1,384 @@ +package config + +import ( + "io/fs" + "os" + "path/filepath" + "runtime" + "sync" + "testing" + + "github.com/devsy-org/devsy/internal/dependencytest" + "github.com/stretchr/testify/require" +) + +type readOnlyTestRoots struct { + config, data, cache, state, runtime, systemBin string +} + +type readOnlyPathCase struct { + name string + fn func() (string, error) + want string +} + +func TestReadOnlyPathManagerPlatformDefaults(t *testing.T) { + root := t.TempDir() + roots := setReadOnlyTestEnvironment(t, root) + dependencytest.Preserve(t, root) + + assertReadOnlyPaths(t, NewReadOnlyPathManager(), roots) +} + +func TestReadOnlyPathManagerHomeOverrides(t *testing.T) { + root := t.TempDir() + defaults := setReadOnlyTestEnvironment(t, root) + t.Chdir(root) + for _, home := range []string{ + filepath.Join(root, "Devsy \u65e5\u672c home"), + root + string(filepath.Separator) + "unused/../lexical home/.", + "./relative home/../\u914d\u7f6e/", + } { + t.Run(home, func(t *testing.T) { + t.Setenv(EnvHome, home) + dependencytest.Preserve(t, root) + assertReadOnlyPaths(t, NewReadOnlyPathManager(), readOnlyTestRoots{ + config: filepath.Clean(home), data: filepath.Clean(home), + cache: filepath.Join(home, "cache"), state: filepath.Join(home, "state"), + runtime: filepath.Join(home, "run"), systemBin: defaults.systemBin, + }) + }) + } +} + +func TestReadOnlyPathManagerConfigOverride(t *testing.T) { + root := t.TempDir() + setReadOnlyTestEnvironment(t, root) + blocked := filepath.Join(root, "file") + require.NoError(t, os.WriteFile(blocked, []byte("unchanged"), 0o600)) + for _, home := range []string{"", blocked} { + t.Run(home, func(t *testing.T) { + t.Setenv(EnvHome, home) + configFile := "./missing/../\u914d\u7f6e config.yaml" + t.Setenv(EnvConfig, configFile) + dependencytest.Preserve(t, root) + for _, pm := range []PathManager{NewReadOnlyPathManager(), NewPathManager()} { + got, err := pm.ConfigFilePath() + require.NoError(t, err) + require.Equal(t, configFile, got) + } + }) + } +} + +func TestReadOnlyPathManagerFileParent(t *testing.T) { + root := t.TempDir() + defaults := setReadOnlyTestEnvironment(t, root) + file := filepath.Join(root, "file parent") + require.NoError(t, os.WriteFile(file, []byte("unchanged"), 0o600)) + t.Setenv(EnvHome, file) + dependencytest.Preserve(t, root) + + assertReadOnlyPaths(t, NewReadOnlyPathManager(), readOnlyTestRoots{ + config: file, data: file, cache: filepath.Join(file, "cache"), + state: filepath.Join(file, "state"), runtime: filepath.Join(file, "run"), + systemBin: defaults.systemBin, + }) +} + +func TestPathManagerCreationFailures(t *testing.T) { + root := t.TempDir() + setReadOnlyTestEnvironment(t, root) + file := filepath.Join(root, "file parent") + require.NoError(t, os.WriteFile(file, []byte("unchanged"), 0o600)) + t.Setenv(EnvHome, file) + dependencytest.Preserve(t, root) + pm := NewPathManager() + paths := append(readOnlyCategoryCases(pm, readOnlyTestRoots{}), readOnlyDataCases(pm, "")...) + paths = append(paths, readOnlyOtherCases(pm, readOnlyTestRoots{})...) + for _, tt := range paths { + t.Run(tt.name, func(t *testing.T) { + got, err := tt.fn() + require.Empty(t, got) + require.ErrorContains(t, err, "create directory ") + var pathErr *os.PathError + require.ErrorAs(t, err, &pathErr) + require.Equal(t, "mkdir", pathErr.Op) + }) + } +} + +func TestPathManagerInstanceIsolation(t *testing.T) { + root := t.TempDir() + setReadOnlyTestEnvironment(t, root) + home := filepath.Join(root, "Devsy \u65e5\u672c home") + t.Setenv(EnvHome, home) + ordinary := NewPathManager() + defaultManager := DefaultPathManager() + readOnly := NewReadOnlyPathManager() + require.Same(t, defaultManager, DefaultPathManager()) + + readOnlyPath, err := readOnly.DependencyLocksDir() + require.NoError(t, err) + require.NoDirExists(t, home) + for _, pm := range []PathManager{ordinary, defaultManager, NewPathManager()} { + for _, tt := range readOnlyCategoryCases(pm, readOnlyTestRoots{}) { + path, err := tt.fn() + require.NoError(t, err) + require.DirExists(t, path) + } + path, err := pm.DependencyLocksDir() + require.NoError(t, err) + require.Equal(t, readOnlyPath, path) + require.NoDirExists(t, path) + require.NoError(t, os.RemoveAll(home)) + path, err = readOnly.DependencyLocksDir() + require.NoError(t, err) + require.Equal(t, readOnlyPath, path) + require.NoDirExists(t, home) + } +} + +func TestPathManagerConcurrentInstanceIsolation(t *testing.T) { + root := t.TempDir() + setReadOnlyTestEnvironment(t, root) + home := filepath.Join(root, "devsy") + t.Setenv(EnvHome, home) + ordinary, readOnly := NewPathManager(), NewReadOnlyPathManager() + var workers sync.WaitGroup + for range 10 { + workers.Go(func() { + path, err := ordinary.CacheDir() + if err != nil || path != filepath.Join(home, "cache") { + t.Errorf("ordinary CacheDir() = %q, %v", path, err) + } + }) + workers.Go(func() { + path, err := readOnly.StateDir() + if err != nil || path != filepath.Join(home, "state") { + t.Errorf("read-only StateDir() = %q, %v", path, err) + } + }) + } + workers.Wait() + require.DirExists(t, filepath.Join(home, "cache")) + require.NoDirExists(t, filepath.Join(home, "state")) +} + +func setReadOnlyTestEnvironment(t *testing.T, root string) readOnlyTestRoots { + t.Helper() + home, temp := filepath.Join(root, "user home"), filepath.Join(root, "temp") + t.Setenv(EnvHome, "") + t.Setenv(EnvConfig, "") + t.Setenv("HOME", home) + t.Setenv("USERPROFILE", home) + t.Setenv("APPDATA", filepath.Join(home, "AppData", "Roaming")) + t.Setenv("LOCALAPPDATA", filepath.Join(home, "AppData", "Local")) + t.Setenv("TMPDIR", temp) + t.Setenv("TMP", temp) + t.Setenv("TEMP", temp) + return readOnlyPlatformTestRoots(home, temp) +} + +func assertReadOnlyPaths(t *testing.T, pm PathManager, roots readOnlyTestRoots) { + t.Helper() + paths := append(readOnlyCategoryCases(pm, roots), readOnlyDataCases(pm, roots.data)...) + paths = append(paths, readOnlyPathCase{"SystemBinDir", pm.SystemBinDir, roots.systemBin}) + paths = append(paths, readOnlyOtherCases(pm, roots)...) + for _, tt := range paths { + t.Run(tt.name, func(t *testing.T) { + got, err := tt.fn() + require.NoError(t, err) + require.Equal(t, tt.want, got) + }) + } +} + +func readOnlyCategoryCases(pm PathManager, r readOnlyTestRoots) []readOnlyPathCase { + return []readOnlyPathCase{ + {"configuration root", pm.ConfigDir, r.config}, + {"data root", pm.DataDir, r.data}, + {"cache root", pm.CacheDir, r.cache}, + {"state root", pm.StateDir, r.state}, + {"runtime root", pm.RuntimeDir, r.runtime}, + } +} + +func readOnlyDataCases(pm PathManager, data string) []readOnlyPathCase { + context := filepath.Join(data, "contexts", "ctx") + provider := filepath.Join(context, "providers", "provider") + return append([]readOnlyPathCase{ + {"ContextDir", func() (string, error) { return pm.ContextDir("ctx") }, context}, + { + "MachinesDir", + func() (string, error) { return pm.MachinesDir("ctx") }, + filepath.Join(context, "machines"), + }, + { + "MachineDir", + func() (string, error) { return pm.MachineDir("ctx", "machine") }, + filepath.Join(context, "machines", "machine"), + }, + { + "ProvidersDir", + func() (string, error) { return pm.ProvidersDir("ctx") }, + filepath.Dir(provider), + }, + { + "ProviderDir", + func() (string, error) { return pm.ProviderDir("ctx", "provider") }, + provider, + }, + { + "ProviderBinariesDir", + func() (string, error) { return pm.ProviderBinariesDir("ctx", "provider") }, + filepath.Join(provider, "binaries"), + }, + { + "ProviderDaemonDir", + func() (string, error) { return pm.ProviderDaemonDir("ctx", "provider") }, + filepath.Join(provider, "daemon"), + }, + { + "PlatformInstancesDir", + func() (string, error) { return pm.PlatformInstancesDir("ctx") }, + filepath.Join(context, "pro_instances"), + }, + { + "PlatformInstanceDir", + func() (string, error) { return pm.PlatformInstanceDir("ctx", "host") }, + filepath.Join(context, "pro_instances", "host"), + }, + { + "LocksDir", + func() (string, error) { return pm.LocksDir("ctx") }, + filepath.Join(context, "locks"), + }, + }, readOnlyWorkspaceCases(pm, context)...) +} + +func readOnlyWorkspaceCases(pm PathManager, context string) []readOnlyPathCase { + ws := filepath.Join(context, "workspaces", "ws") + return []readOnlyPathCase{ + { + "WorkspacesDir", + func() (string, error) { return pm.WorkspacesDir("ctx") }, + filepath.Dir(ws), + }, + {"WorkspaceDir", func() (string, error) { return pm.WorkspaceDir("ctx", "ws") }, ws}, + { + "WorkspaceAgentDir", + func() (string, error) { return pm.WorkspaceAgentDir("ctx", "ws") }, + filepath.Join(ws, "agent"), + }, + { + "WorkspaceLogDir", + func() (string, error) { return pm.WorkspaceLogDir("ctx", "ws") }, + filepath.Join(ws, "logs"), + }, + { + "WorkspaceContentsDir", + func() (string, error) { return pm.WorkspaceContentsDir("ctx") }, + filepath.Join(context, "contents"), + }, + { + "WorkspaceContentDir", + func() (string, error) { return pm.WorkspaceContentDir("ctx", "ws") }, + filepath.Join(context, "contents", "ws"), + }, + } +} + +func readOnlyOtherCases(pm PathManager, r readOnlyTestRoots) []readOnlyPathCase { + return []readOnlyPathCase{ + {"ConfigFilePath", pm.ConfigFilePath, filepath.Join(r.config, ConfigFile)}, + {"DependencyToolsDir", pm.DependencyToolsDir, filepath.Join(r.data, "tools")}, + { + "DependencyDownloadCacheDir", + pm.DependencyDownloadCacheDir, + filepath.Join(r.cache, "dependencies"), + }, + {"DependencyStateDir", pm.DependencyStateDir, filepath.Join(r.state, "dependencies")}, + { + "DependencyLocksDir", + pm.DependencyLocksDir, + filepath.Join(r.state, "dependencies", "locks"), + }, + {"AgentCacheDir", pm.AgentCacheDir, filepath.Join(r.cache, "agents")}, + { + "ProviderDownloadCacheDir", + pm.ProviderDownloadCacheDir, + filepath.Join(r.cache, "providers"), + }, + { + "FeatureCacheDir", + func() (string, error) { return pm.FeatureCacheDir("hash") }, + filepath.Join(r.cache, "features", "hash"), + }, + {"PlatformCacheDir", pm.PlatformCacheDir, filepath.Join(r.cache, "platform")}, + {"SSHKeysDir", pm.SSHKeysDir, filepath.Join(r.cache, "keys")}, + {"DaemonPIDFile", pm.DaemonPIDFile, filepath.Join(r.runtime, DaemonProcessName+".pid")}, + {"DaemonLockFile", pm.DaemonLockFile, filepath.Join(r.runtime, DaemonProcessName+".lock")}, + { + "DaemonStreamsFile", + pm.DaemonStreamsFile, + filepath.Join(r.runtime, DaemonProcessName+".streams"), + }, + { + "ProcessPIDFile", + func() (string, error) { return pm.ProcessPIDFile("proc") }, + filepath.Join(r.runtime, "proc.pid"), + }, + { + "ProcessLockFile", + func() (string, error) { return pm.ProcessLockFile("proc") }, + filepath.Join(r.runtime, "proc.lock"), + }, + { + "ProcessStreamsFile", + func() (string, error) { return pm.ProcessStreamsFile("proc") }, + filepath.Join(r.runtime, "proc.streams"), + }, + {"LogDir", pm.LogDir, filepath.Join(r.state, "logs")}, + {"TaskDir", pm.TaskDir, filepath.Join(r.state, "tasks")}, + } +} + +func TestReadOnlyPathManagerPreservesExistingTree(t *testing.T) { + root := t.TempDir() + setReadOnlyTestEnvironment(t, root) + home := filepath.Join(root, "existing home") + require.NoError(t, os.MkdirAll(home, 0o700)) + require.NoError(t, os.WriteFile(filepath.Join(home, "keep"), []byte("existing data"), 0o600)) + t.Setenv(EnvHome, home) + dependencytest.Preserve(t, root) + pm := NewReadOnlyPathManager() + for _, tt := range readOnlyOtherCases(pm, readOnlyTestRoots{}) { + _, err := tt.fn() + require.NoError(t, err) + } + _, err := os.Stat(filepath.Join(home, "cache")) + require.ErrorIs(t, err, fs.ErrNotExist) +} + +func TestReadOnlyPathManagerMissingEnvironment(t *testing.T) { + root := t.TempDir() + setReadOnlyTestEnvironment(t, root) + for _, name := range []string{"HOME", "USERPROFILE", "APPDATA", "LOCALAPPDATA"} { + t.Setenv(name, "") + } + dependencytest.Preserve(t, root) + envName := "HOME" + if runtime.GOOS == "windows" { + envName = "APPDATA" + } + for _, pm := range []PathManager{NewReadOnlyPathManager(), NewPathManager()} { + for _, fn := range []func() (string, error){ + pm.ConfigDir, pm.DataDir, pm.CacheDir, pm.StateDir, pm.ConfigFilePath, + } { + got, err := fn() + require.Empty(t, got) + require.ErrorContains(t, err, envName) + } + } +} diff --git a/pkg/config/pathmanager_unix.go b/pkg/config/pathmanager_unix.go index 139dfd41f3..7cf13b21cb 100644 --- a/pkg/config/pathmanager_unix.go +++ b/pkg/config/pathmanager_unix.go @@ -12,61 +12,61 @@ type unixPathManager struct { basePathManager } -func newPlatformPathManager() PathManager { - pm := &unixPathManager{} +func newPlatformPathManager(settings pathManagerSettings) PathManager { + pm := &unixPathManager{basePathManager: basePathManager{pathManagerSettings: settings}} pm.pm = pm return pm } func (u *unixPathManager) ConfigDir() (string, error) { - if dir, ok, err := homeOverrideDir(); ok { + if dir, ok, err := u.homeOverrideDir(); ok { return dir, err } home, err := os.UserHomeDir() if err != nil { return "", fmt.Errorf("config dir: %w", err) } - return ensureDir(filepath.Join(home, "."+RepoName)) + return u.ensureDir(filepath.Join(home, "."+RepoName)) } func (u *unixPathManager) DataDir() (string, error) { - if dir, ok, err := homeOverrideDir(); ok { + if dir, ok, err := u.homeOverrideDir(); ok { return dir, err } home, err := os.UserHomeDir() if err != nil { return "", fmt.Errorf("data dir: %w", err) } - return ensureDir(filepath.Join(home, "."+RepoName)) + return u.ensureDir(filepath.Join(home, "."+RepoName)) } func (u *unixPathManager) CacheDir() (string, error) { - if dir, ok, err := homeOverrideDir("cache"); ok { + if dir, ok, err := u.homeOverrideDir("cache"); ok { return dir, err } home, err := os.UserHomeDir() if err != nil { return "", fmt.Errorf("cache dir: %w", err) } - return ensureDir(filepath.Join(home, ".cache", RepoName)) + return u.ensureDir(filepath.Join(home, ".cache", RepoName)) } func (u *unixPathManager) StateDir() (string, error) { - if dir, ok, err := homeOverrideDir("state"); ok { + if dir, ok, err := u.homeOverrideDir("state"); ok { return dir, err } home, err := os.UserHomeDir() if err != nil { return "", fmt.Errorf("state dir: %w", err) } - return ensureDir(filepath.Join(home, "."+RepoName, "state")) + return u.ensureDir(filepath.Join(home, "."+RepoName, "state")) } func (u *unixPathManager) RuntimeDir() (string, error) { - if dir, ok, err := homeOverrideDir("run"); ok { + if dir, ok, err := u.homeOverrideDir("run"); ok { return dir, err } - return ensureDir(filepath.Join(os.TempDir(), fmt.Sprintf("%s-%d", RepoName, os.Getuid()))) + return u.ensureDir(filepath.Join(os.TempDir(), fmt.Sprintf("%s-%d", RepoName, os.Getuid()))) } func (u *unixPathManager) SystemBinDir() (string, error) { diff --git a/pkg/config/pathmanager_unix_test.go b/pkg/config/pathmanager_unix_test.go new file mode 100644 index 0000000000..b9596c9882 --- /dev/null +++ b/pkg/config/pathmanager_unix_test.go @@ -0,0 +1,24 @@ +//go:build unix && !linux && !darwin + +package config + +import ( + "fmt" + "os" + "path/filepath" +) + +func readOnlyPlatformTestRoots(home, temp string) readOnlyTestRoots { + data := filepath.Join(home, "."+RepoName) + return readOnlyTestRoots{ + config: data, + data: data, + cache: filepath.Join(home, ".cache", RepoName), + state: filepath.Join( + data, + "state", + ), + runtime: filepath.Join(temp, fmt.Sprintf("%s-%d", RepoName, os.Getuid())), + systemBin: "/usr/local/bin", + } +} diff --git a/pkg/config/pathmanager_windows.go b/pkg/config/pathmanager_windows.go index cbaaec5567..51ea825f72 100644 --- a/pkg/config/pathmanager_windows.go +++ b/pkg/config/pathmanager_windows.go @@ -12,15 +12,15 @@ type windowsPathManager struct { basePathManager } -func newPlatformPathManager() PathManager { - pm := &windowsPathManager{} +func newPlatformPathManager(settings pathManagerSettings) PathManager { + pm := &windowsPathManager{basePathManager: basePathManager{pathManagerSettings: settings}} pm.pm = pm return pm } func (w *windowsPathManager) ConfigDir() (string, error) { - if dir, ok, err := homeOverrideDir(); ok { + if dir, ok, err := w.homeOverrideDir(); ok { return dir, err } @@ -29,11 +29,11 @@ func (w *windowsPathManager) ConfigDir() (string, error) { return "", fmt.Errorf("config dir: APPDATA environment variable is not set") } - return ensureDir(filepath.Join(appData, RepoName)) + return w.ensureDir(filepath.Join(appData, RepoName)) } func (w *windowsPathManager) DataDir() (string, error) { - if dir, ok, err := homeOverrideDir(); ok { + if dir, ok, err := w.homeOverrideDir(); ok { return dir, err } @@ -42,11 +42,11 @@ func (w *windowsPathManager) DataDir() (string, error) { return "", fmt.Errorf("data dir: LOCALAPPDATA environment variable is not set") } - return ensureDir(filepath.Join(localAppData, RepoName)) + return w.ensureDir(filepath.Join(localAppData, RepoName)) } func (w *windowsPathManager) CacheDir() (string, error) { - if dir, ok, err := homeOverrideDir("cache"); ok { + if dir, ok, err := w.homeOverrideDir("cache"); ok { return dir, err } @@ -55,11 +55,11 @@ func (w *windowsPathManager) CacheDir() (string, error) { return "", fmt.Errorf("cache dir: LOCALAPPDATA environment variable is not set") } - return ensureDir(filepath.Join(localAppData, RepoName, "cache")) + return w.ensureDir(filepath.Join(localAppData, RepoName, "cache")) } func (w *windowsPathManager) StateDir() (string, error) { - if dir, ok, err := homeOverrideDir("state"); ok { + if dir, ok, err := w.homeOverrideDir("state"); ok { return dir, err } @@ -68,15 +68,15 @@ func (w *windowsPathManager) StateDir() (string, error) { return "", fmt.Errorf("state dir: LOCALAPPDATA environment variable is not set") } - return ensureDir(filepath.Join(localAppData, RepoName, "state")) + return w.ensureDir(filepath.Join(localAppData, RepoName, "state")) } func (w *windowsPathManager) RuntimeDir() (string, error) { - if dir, ok, err := homeOverrideDir("run"); ok { + if dir, ok, err := w.homeOverrideDir("run"); ok { return dir, err } - return ensureDir(filepath.Join(os.TempDir(), RepoName)) + return w.ensureDir(filepath.Join(os.TempDir(), RepoName)) } // SystemBinDir returns a PATH directory for installing standalone tool binaries. diff --git a/pkg/config/pathmanager_windows_test.go b/pkg/config/pathmanager_windows_test.go new file mode 100644 index 0000000000..039424edfe --- /dev/null +++ b/pkg/config/pathmanager_windows_test.go @@ -0,0 +1,17 @@ +//go:build windows + +package config + +import ( + "path/filepath" +) + +func readOnlyPlatformTestRoots(home, temp string) readOnlyTestRoots { + data := filepath.Join(home, "AppData", "Local", RepoName) + return readOnlyTestRoots{ + config: filepath.Join(home, "AppData", "Roaming", RepoName), + data: data, cache: filepath.Join(data, "cache"), state: filepath.Join(data, "state"), + runtime: filepath.Join(temp, RepoName), + systemBin: filepath.Join(home, "AppData", "Local", "Microsoft", "WindowsApps"), + } +} diff --git a/pkg/dependencies/catalog.go b/pkg/dependencies/catalog.go new file mode 100644 index 0000000000..899f13d11e --- /dev/null +++ b/pkg/dependencies/catalog.go @@ -0,0 +1,246 @@ +package dependencies + +import ( + "bytes" + "crypto/sha256" + _ "embed" + "encoding/hex" + "encoding/json" + "errors" + "fmt" + "io" + "slices" + "strings" + + "github.com/blang/semver/v4" +) + +//go:embed catalog/v1.json +var embeddedCatalog string + +type catalogDocument struct { + SchemaVersion int `json:"schemaVersion"` + ID string `json:"id"` + ManagedStatus string `json:"managedStatus"` + Bindings []Binding `json:"bindings"` + Recipes []Recipe `json:"recipes"` +} + +type Catalog struct { + document catalogDocument + hash string +} + +func LoadCatalog() (*Catalog, error) { + return decodeCatalog([]byte(embeddedCatalog)) +} + +func decodeCatalog(data []byte) (*Catalog, error) { + if err := checkJSONValue(json.NewDecoder(bytes.NewReader(data))); err != nil { + return nil, fmt.Errorf("invalid dependency catalog JSON: %w", err) + } + decoder := json.NewDecoder(bytes.NewReader(data)) + decoder.DisallowUnknownFields() + var document catalogDocument + if err := decoder.Decode(&document); err != nil { + return nil, fmt.Errorf("decode dependency catalog: %w", err) + } + if err := decoder.Decode(new(any)); !errors.Is(err, io.EOF) { + return nil, errors.New("dependency catalog has trailing data") + } + if err := document.validate(); err != nil { + return nil, err + } + canonical, err := json.Marshal(document) + if err != nil { + return nil, fmt.Errorf("encode dependency catalog identity: %w", err) + } + digest := sha256.Sum256(canonical) + return &Catalog{document: document, hash: hex.EncodeToString(digest[:])}, nil +} + +func checkJSONValue(decoder *json.Decoder) error { + token, err := decoder.Token() + if err != nil { + return err + } + switch token { + case nil: + return errors.New("null catalog metadata is forbidden") + case json.Delim('{'): + return checkJSONObject(decoder) + case json.Delim('['): + for decoder.More() { + if err := checkJSONValue(decoder); err != nil { + return err + } + } + _, err = decoder.Token() + return err + default: + return nil + } +} + +func checkJSONObject(decoder *json.Decoder) error { + seen := make(map[string]bool) + for decoder.More() { + token, err := decoder.Token() + if err != nil { + return err + } + key, ok := token.(string) + if !ok || seen[key] { + return errors.New("duplicate or invalid JSON object key") + } + seen[key] = true + if err := checkJSONValue(decoder); err != nil { + return err + } + } + _, err := decoder.Token() + return err +} + +func (c *Catalog) ID() string { return c.document.ID } + +func (c *Catalog) Hash() string { return c.hash } + +func (c *Catalog) ManagedStatus() string { return c.document.ManagedStatus } + +func (c *Catalog) Bindings() []Binding { + bindings := slices.Clone(c.document.Bindings) + for i := range bindings { + bindings[i].Platforms = slices.Clone(bindings[i].Platforms) + bindings[i].Requirements = cloneRequirements(bindings[i].Requirements) + } + return bindings +} + +func (c *Catalog) Recipes() []Recipe { + recipes := slices.Clone(c.document.Recipes) + for i := range recipes { + recipes[i].Members = slices.Clone(recipes[i].Members) + recipes[i].Prerequisites = slices.Clone(recipes[i].Prerequisites) + recipes[i].Actions = slices.Clone(recipes[i].Actions) + } + return recipes +} + +func (c *Catalog) Match(contract ProviderContract) (ContractMatch, error) { + if err := validateContractFacts(contract); err != nil { + return ContractMatch{}, err + } + for _, binding := range c.document.Bindings { + if binding.Source == contract.Source { + return matchBinding(binding, contract), nil + } + } + return ContractMatch{ManagedReason: "dependency_policy_blocked"}, nil +} + +func matchBinding(binding Binding, contract ProviderContract) ContractMatch { + match := ContractMatch{ + BindingID: binding.ID, GuidanceID: binding.GuidanceID, + ManagedReason: "dependency_recipe_unqualified", AdapterStatus: "not_applicable", + ContractVerified: binding.ExecutionContract == contract.ExecutionContract, + } + if binding.Source.Kind == SourceGitHub { + match.AdapterStatus = "version_unqualified" + if contract.AdapterVersion == "" { + match.AdapterStatus = "version_unknown" + } + } + if !match.ContractVerified { + match.ManagedReason = "dependency_policy_blocked" + return match + } + imageBackend := contract.ImageBackend + // The existing external driver defaults an omitted image backend to Docker. + if imageBackend == "" { + imageBackend = toolDocker + } + for _, requirement := range binding.Requirements { + if requirement.WhenImageBackend == "" || + requirement.WhenImageBackend == imageBackend { + match.Requirements = append(match.Requirements, requirement) + } + } + match.Requirements = cloneRequirements(match.Requirements) + // No released adapter range or qualified recipe exists; caller-supplied facts cannot enable installation. + return match +} + +func cloneRequirements(requirements []Requirement) []Requirement { + cloned := slices.Clone(requirements) + for i := range cloned { + cloned[i].RequiredFor = slices.Clone(cloned[i].RequiredFor) + } + return cloned +} + +func validateContractFacts(contract ProviderContract) error { + if err := validateSource(contract.Source); err != nil { + return err + } + if contract.AdapterVersion != "" { + if _, err := semver.Parse(strings.TrimPrefix(contract.AdapterVersion, "v")); err != nil { + return fmt.Errorf("invalid provider adapter version: %w", err) + } + } + if contract.ManifestSHA256 != "" && !validSHA256(contract.ManifestSHA256) { + return errors.New("invalid provider manifest SHA-256") + } + if contract.RuntimeCheckSchema < 0 { + return errors.New("invalid runtime-check schema version") + } + if !slices.Contains([]string{"", toolDocker, imageBackendNone}, contract.ImageBackend) { + return errors.New("unknown image backend") + } + return nil +} + +func validateSource(source ProviderSource) error { + identities := 0 + for _, value := range []string{source.InternalID, source.Repository, source.Location} { + if value != "" { + identities++ + } + } + if identities != 1 || !validSourceIdentity(source) { + return errors.New("ambiguous or malformed provider source") + } + return nil +} + +func validSourceIdentity(source ProviderSource) bool { + switch source.Kind { + case SourceInternal: + return plainName(source.InternalID) + case SourceGitHub: + return canonicalRepository(source.Repository) + case SourceURL, SourceFile: + return source.Location != "" + default: + return false + } +} + +func canonicalRepository(repository string) bool { + parts := strings.Split(repository, "/") + return len(parts) == 3 && parts[0] == "github.com" && plainName(parts[1]) && plainName(parts[2]) +} + +func plainName(value string) bool { + if value == "" || value == "." || value == ".." { + return false + } + return strings.IndexFunc(value, func(r rune) bool { + return !strings.ContainsRune("abcdefghijklmnopqrstuvwxyz0123456789-_.", r) + }) == -1 +} + +func validSHA256(value string) bool { + decoded, err := hex.DecodeString(value) + return err == nil && len(decoded) == sha256.Size && value == strings.ToLower(value) +} diff --git a/pkg/dependencies/catalog/v1.json b/pkg/dependencies/catalog/v1.json new file mode 100644 index 0000000000..ea7e24f272 --- /dev/null +++ b/pkg/dependencies/catalog/v1.json @@ -0,0 +1,202 @@ +{ + "schemaVersion": 1, + "id": "devsy.dependencies.catalog.v1", + "managedStatus": "no_qualified_recipe", + "bindings": [ + { + "id": "docker", + "source": { + "kind": "internal", + "internalId": "docker" + }, + "executionContract": "internal_docker", + "adapterSemverRange": "", + "requiredRuntimeCheckSchema": 0, + "platforms": [ + "linux/amd64", + "linux/arm64", + "darwin/amd64", + "darwin/arm64", + "windows/amd64", + "windows/arm64" + ], + "guidanceId": "docker_setup", + "requirements": [ + { + "toolId": "docker", + "purpose": "container_runtime", + "scope": "controller_host", + "requiredFor": ["create", "exec", "stop", "delete"], + "guidanceId": "docker_setup", + "executableOption": "DOCKER_PATH", + "probeId": "docker_version" + } + ] + }, + { + "id": "podman", + "source": { + "kind": "internal", + "internalId": "podman" + }, + "executionContract": "internal_podman", + "adapterSemverRange": "", + "requiredRuntimeCheckSchema": 0, + "platforms": [ + "linux/amd64", + "linux/arm64", + "darwin/amd64", + "darwin/arm64", + "windows/amd64", + "windows/arm64" + ], + "guidanceId": "podman_setup", + "requirements": [ + { + "toolId": "podman", + "purpose": "container_runtime", + "scope": "controller_host", + "requiredFor": ["create", "exec", "stop", "delete"], + "guidanceId": "podman_setup", + "executableOption": "PODMAN_PATH", + "probeId": "podman_version" + } + ] + }, + { + "id": "apple", + "source": { + "kind": "internal", + "internalId": "apple" + }, + "executionContract": "internal_apple", + "adapterSemverRange": "", + "requiredRuntimeCheckSchema": 0, + "platforms": ["darwin/arm64"], + "guidanceId": "apple_container_setup", + "requirements": [ + { + "toolId": "apple-container", + "purpose": "container_runtime", + "scope": "controller_host", + "requiredFor": ["create", "exec", "stop", "delete"], + "guidanceId": "apple_container_setup", + "executableOption": "CONTAINER_PATH", + "probeId": "container_version" + } + ] + }, + { + "id": "kubernetes", + "source": { + "kind": "internal", + "internalId": "kubernetes" + }, + "executionContract": "internal_kubernetes", + "adapterSemverRange": "", + "requiredRuntimeCheckSchema": 0, + "platforms": [ + "linux/amd64", + "linux/arm64", + "darwin/amd64", + "darwin/arm64", + "windows/amd64", + "windows/arm64" + ], + "guidanceId": "kubernetes_configuration", + "requirements": [ + { + "toolId": "kubernetes-config", + "purpose": "cluster_configuration", + "scope": "controller_host", + "requiredFor": ["create", "exec", "stop", "delete"], + "guidanceId": "kubernetes_configuration", + "configurationOption": "KUBERNETES_CONFIG" + } + ] + }, + { + "id": "microsandbox", + "source": { + "kind": "github", + "repository": "github.com/devsy-org/devsy-provider-microsandbox" + }, + "executionContract": "external_microsandbox_v1", + "adapterSemverRange": "", + "requiredRuntimeCheckSchema": 1, + "platforms": ["linux/amd64", "linux/arm64", "darwin/arm64"], + "guidanceId": "microsandbox_setup", + "requirements": [ + { + "toolId": "microsandbox", + "purpose": "microvm_runtime", + "scope": "controller_host", + "requiredFor": ["create", "exec", "stop", "delete"], + "guidanceId": "microsandbox_setup", + "probeId": "microsandbox_version" + }, + { + "toolId": "docker", + "purpose": "image_backend", + "scope": "controller_host", + "requiredFor": ["create", "image-build"], + "probeId": "docker_version", + "guidanceId": "docker_setup", + "whenImageBackend": "docker" + } + ] + }, + { + "id": "lima", + "source": { + "kind": "github", + "repository": "github.com/devsy-org/devsy-provider-lima" + }, + "executionContract": "lima_exec_v1", + "adapterSemverRange": "", + "requiredRuntimeCheckSchema": 0, + "platforms": [ + "linux/amd64", + "linux/arm64", + "darwin/amd64", + "darwin/arm64" + ], + "guidanceId": "lima_setup", + "requirements": [ + { + "toolId": "lima", + "purpose": "vm_runtime", + "scope": "controller_host", + "requiredFor": ["create", "exec", "stop", "delete"], + "guidanceId": "lima_setup", + "executableOption": "LIMA_PATH", + "probeId": "limactl_version" + } + ] + }, + { + "id": "orbstack", + "source": { + "kind": "github", + "repository": "github.com/devsy-org/devsy-provider-orbstack" + }, + "executionContract": "orbstack_exec_v1", + "adapterSemverRange": "", + "requiredRuntimeCheckSchema": 0, + "platforms": ["darwin/amd64", "darwin/arm64"], + "guidanceId": "orbstack_setup", + "requirements": [ + { + "toolId": "orbstack", + "purpose": "vm_runtime", + "scope": "controller_host", + "requiredFor": ["create", "exec", "stop", "delete"], + "guidanceId": "orbstack_setup", + "executableOption": "ORBSTACK_PATH", + "probeId": "orbctl_version" + } + ] + } + ], + "recipes": [] +} diff --git a/pkg/dependencies/catalog_recipe.go b/pkg/dependencies/catalog_recipe.go new file mode 100644 index 0000000000..04162856ae --- /dev/null +++ b/pkg/dependencies/catalog_recipe.go @@ -0,0 +1,145 @@ +package dependencies + +import ( + "errors" + "fmt" + "slices" + "strings" + + "github.com/blang/semver/v4" +) + +const maxCatalogArchiveBytes int64 = 1 << 30 + +func validateRecipes(recipes []Recipe) error { + identities := make(map[string]bool) + for _, recipe := range recipes { + keys := []string{ + "id:" + recipe.ID, + "tuple:" + recipe.ToolID + ":" + recipe.RuntimeVersion + ":" + recipe.Platform, + "url:" + recipe.URL, + "sha256:" + recipe.SHA256, + } + for _, key := range keys { + if identities[key] { + return fmt.Errorf("duplicate recipe identity %q", key) + } + identities[key] = true + } + if err := validateRecipe(recipe); err != nil { + return fmt.Errorf("recipe %q: %w", recipe.ID, err) + } + } + return nil +} + +func validateRecipe(recipe Recipe) error { + if recipe.Enabled { + return errors.New( + "enabled recipes require unavailable qualification and released-adapter gates", + ) + } + if !plainName(recipe.ID) || recipe.ToolID != toolMicrosandbox { + return errors.New("unrecognized recipe identity or tool") + } + if err := validateRecipeQualification(recipe); err != nil { + return err + } + if _, err := semver.Parse(strings.TrimPrefix(recipe.RuntimeVersion, "v")); err != nil { + return fmt.Errorf("invalid upstream runtime version: %w", err) + } + if err := validateRecipeArtifact(recipe); err != nil { + return err + } + if err := validateRecipeMembers(recipe); err != nil { + return err + } + return validateRecipeChecks(recipe) +} + +func validateRecipeQualification(recipe Recipe) error { + if !slices.Contains( + []string{"not_run", "source_recorded_unqualified", "blocked"}, + recipe.QualificationStatus, + ) || + recipe.QualificationRecord != "" { + return errors.New("no qualification records have been approved") + } + return nil +} + +func validateRecipeArtifact(recipe Recipe) error { + if recipe.Platform != platformLinuxAMD64 { + return errors.New("no reviewed archive layout for this platform") + } + if recipe.ArchiveFormat != "tar.gz" || recipe.Layout != "flat_verbatim_no_links" { + return errors.New("unsupported archive format or layout") + } + if !validSHA256(recipe.SHA256) { + return errors.New("invalid archive SHA-256") + } + if !boundedArchiveSize(recipe.MaxArchiveBytes) || !boundedArchiveSize(recipe.MaxExpandedBytes) { + return errors.New("archive size bounds must be positive and at most 1 GiB") + } + return validateRecipeURL(recipe) +} + +func boundedArchiveSize(size int64) bool { + return size > 0 && size <= maxCatalogArchiveBytes +} + +func validateRecipeURL(recipe Recipe) error { + expectedURL := "https://github.com/superradcompany/microsandbox/releases/download/" + recipe.RuntimeVersion + + "/microsandbox-linux-x86_64.tar.gz" + if !strings.HasPrefix(recipe.RuntimeVersion, "v") || recipe.URL != expectedURL { + return errors.New("release asset must name an exact upstream version and allowlisted asset") + } + return nil +} + +func validateRecipeMembers(recipe Recipe) error { + if recipe.Executable != "msb" || recipe.Firmware != "libkrunfw.so.5.6.1" || + len(recipe.Members) != 2 { + return errors.New("unsupported runtime pair or archive inventory") + } + seen := make(map[string]bool) + var expandedBytes int64 + for _, member := range recipe.Members { + if seen[member.Name] { + return errors.New("duplicate archive member") + } + seen[member.Name] = true + if err := validateRecipeMember(member, recipe); err != nil { + return err + } + expandedBytes += member.MaxBytes + } + if expandedBytes > recipe.MaxExpandedBytes { + return errors.New("member size bounds exceed expanded archive bound") + } + return nil +} + +func validateRecipeMember(member ArchiveMember, recipe Recipe) error { + if member.Name != recipe.Executable && member.Name != recipe.Firmware { + return errors.New("archive member must name the reviewed flat runtime pair") + } + if member.Type != "regular" { + return errors.New("non-regular archive member; links are forbidden") + } + if member.MaxBytes <= 0 || member.MaxBytes > recipe.MaxExpandedBytes { + return errors.New("invalid archive member size bound") + } + return nil +} + +func validateRecipeChecks(recipe Recipe) error { + if recipe.ProbeID != "microsandbox_version" || + !slices.Equal(recipe.Prerequisites, []string{"kvm"}) { + return errors.New("unrecognized recipe probe or prerequisites") + } + if !slices.Equal(recipe.Actions, []string{"install", "select", "remove"}) { + return errors.New("unrecognized recipe actions") + } + return nil +} diff --git a/pkg/dependencies/catalog_test.go b/pkg/dependencies/catalog_test.go new file mode 100644 index 0000000000..7f39271824 --- /dev/null +++ b/pkg/dependencies/catalog_test.go @@ -0,0 +1,253 @@ +package dependencies + +import ( + "bytes" + "encoding/json" + "strings" + "testing" + + "github.com/stretchr/testify/suite" +) + +type catalogSuite struct { + suite.Suite +} + +const ( + testCustom = "custom" + testShell = "shell" +) + +func TestCatalog(t *testing.T) { + suite.Run(t, new(catalogSuite)) +} + +func (s *catalogSuite) TestInternalIdentityCannotBeInheritedByDisplayName() { + catalog, err := LoadCatalog() + s.Require().NoError(err) + for _, binding := range catalog.Bindings()[:4] { + s.Run(binding.ID, func() { + match, matchErr := catalog.Match(ProviderContract{ + DisplayName: "renamed-provider", Source: binding.Source, + ExecutionContract: binding.ExecutionContract, + }) + s.Require().NoError(matchErr) + s.Equal(binding.ID, match.BindingID) + s.True(match.ContractVerified) + s.False(match.ManagedEligible) + custom, customErr := catalog.Match(ProviderContract{ + DisplayName: binding.ID, + Source: ProviderSource{Kind: SourceFile, Location: "/tmp/provider.yaml"}, + ExecutionContract: binding.ExecutionContract, + }) + s.Require().NoError(customErr) + s.Empty(custom.BindingID) + s.Empty(custom.Requirements) + s.False(custom.ManagedEligible) + }) + } +} + +func (s *catalogSuite) TestCanonicalExternalAliasesAndAdapterFacts() { + catalog, err := LoadCatalog() + s.Require().NoError(err) + for _, binding := range catalog.Bindings()[4:] { + s.Run(binding.ID, func() { + for _, version := range []string{"", "v0.1.11", "0.0.1", "99.0.0"} { + match, matchErr := catalog.Match(ProviderContract{ + DisplayName: "my-alias", Source: binding.Source, AdapterVersion: version, + ExecutionContract: binding.ExecutionContract, RuntimeCheckSchema: 1, + ManifestSHA256: strings.Repeat("a", 64), ImageBackend: imageBackendNone, + }) + s.Require().NoError(matchErr) + s.True(match.ContractVerified) + s.Equal(binding.ID, match.BindingID) + s.Len(match.Requirements, 1) + s.False(match.ManagedEligible) + s.Equal("dependency_recipe_unqualified", match.ManagedReason) + if version == "" { + s.Equal("version_unknown", match.AdapterStatus) + } else { + s.Equal("version_unqualified", match.AdapterStatus) + } + } + }) + } +} + +func (s *catalogSuite) TestKnownOriginWithoutExecutionContractHasGuidanceOnly() { + catalog, err := LoadCatalog() + s.Require().NoError(err) + for _, execution := range []string{"", testCustom, executionDocker} { + match, matchErr := catalog.Match(ProviderContract{ + Source: externalSource(toolMicrosandbox), ExecutionContract: execution, + }) + s.Require().NoError(matchErr) + s.Equal(toolMicrosandbox, match.BindingID) + s.Equal("microsandbox_setup", match.GuidanceID) + s.Empty(match.Requirements) + s.False(match.ContractVerified) + s.False(match.ManagedEligible) + } +} + +func (s *catalogSuite) TestLookalikesAndCanonicalLookingURLsAreUnmanaged() { + catalog, err := LoadCatalog() + s.Require().NoError(err) + sources := []ProviderSource{ + {Kind: SourceGitHub, Repository: "github.com/evil/devsy-provider-microsandbox"}, + {Kind: SourceGitHub, Repository: "github.com/devsy-org/devsy-provider-microsandbox-evil"}, + {Kind: SourceGitHub, Repository: "github.com/devsy-org/devsy-provider-microsandbox.git"}, + {Kind: SourceURL, Location: "https://github.com/devsy-org/devsy-provider-microsandbox"}, + { + Kind: SourceURL, + Location: "https://github.com.evil/devsy-org/devsy-provider-microsandbox", + }, + {Kind: SourceInternal, InternalID: toolMicrosandbox}, + } + for _, source := range sources { + match, matchErr := catalog.Match(ProviderContract{ + DisplayName: toolMicrosandbox, + Source: source, + ExecutionContract: executionMicrosandbox, + }) + s.Require().NoError(matchErr) + s.Empty(match.BindingID) + s.Empty(match.Requirements) + s.False(match.ManagedEligible) + } +} + +func (s *catalogSuite) TestMalformedAndConflictingSourceFactsFailClosed() { + catalog, err := LoadCatalog() + s.Require().NoError(err) + cases := []ProviderContract{ + { + Source: ProviderSource{ + Kind: SourceGitHub, + Repository: externalSource(toolLima).Repository, + InternalID: toolDocker, + }, + }, + { + Source: ProviderSource{ + Kind: SourceInternal, + InternalID: toolDocker, + Location: "/tmp/provider.yaml", + }, + }, + {Source: ProviderSource{Kind: testCustom, InternalID: toolDocker}}, + { + Source: ProviderSource{ + Kind: SourceGitHub, + Repository: externalSource(toolLima).Repository + "/suffix", + }, + }, + { + Source: ProviderSource{ + Kind: SourceGitHub, + Repository: "https://github.com/devsy-org/devsy-provider-lima", + }, + }, + { + Source: ProviderSource{ + Kind: SourceGitHub, + Repository: externalSource(toolLima).Repository + "@v1.1.0", + }, + }, + {Source: externalSource(toolLima), AdapterVersion: "latest"}, + {Source: externalSource(toolLima), AdapterVersion: "1.1"}, + {Source: externalSource(toolLima), ManifestSHA256: "abc"}, + {Source: externalSource(toolLima), RuntimeCheckSchema: -1}, + {Source: externalSource(toolLima), ImageBackend: testCustom}, + } + for i, contract := range cases { + match, matchErr := catalog.Match(contract) + s.Error(matchErr, "case %d", i) + s.False(match.ManagedEligible) + s.Empty(match.Requirements) + } +} + +func (s *catalogSuite) TestMicroSandboxImageBackendIsConditional() { + catalog, err := LoadCatalog() + s.Require().NoError(err) + contract := ProviderContract{ + Source: externalSource(toolMicrosandbox), + ExecutionContract: executionMicrosandbox, + } + for _, backend := range []string{"", imageBackendNone, toolDocker} { + contract.ImageBackend = backend + match, matchErr := catalog.Match(contract) + s.Require().NoError(matchErr) + s.Equal(toolMicrosandbox, match.Requirements[0].ToolID) + s.Empty(match.Requirements[0].ExecutableOption) + if backend != imageBackendNone { + s.Len(match.Requirements, 2) + s.Equal("image_backend", match.Requirements[1].Purpose) + s.Empty(match.Requirements[1].ExecutableOption) + } else { + s.Len(match.Requirements, 1) + } + } +} + +func (s *catalogSuite) TestKubernetesHasNoExecutableProbeOrKubectlDependency() { + catalog, err := LoadCatalog() + s.Require().NoError(err) + match, err := catalog.Match(ProviderContract{ + Source: ProviderSource{ + Kind: SourceInternal, + InternalID: "kubernetes", + }, + ExecutionContract: "internal_kubernetes", + }) + s.Require().NoError(err) + s.Require().Len(match.Requirements, 1) + s.Equal("kubernetes-config", match.Requirements[0].ToolID) + s.Equal("KUBERNETES_CONFIG", match.Requirements[0].ConfigurationOption) + s.Empty(match.Requirements[0].ExecutableOption) + s.Empty(match.Requirements[0].ProbeID) +} + +func (s *catalogSuite) TestCatalogIdentityAndCopies() { + catalog, err := LoadCatalog() + s.Require().NoError(err) + s.Equal("devsy.dependencies.catalog.v1", catalog.ID()) + s.Equal("no_qualified_recipe", catalog.ManagedStatus()) + var compact bytes.Buffer + s.Require().NoError(json.Compact(&compact, []byte(embeddedCatalog))) + copyCatalog, err := decodeCatalog(compact.Bytes()) + s.Require().NoError(err) + s.Equal(catalog.Hash(), copyCatalog.Hash()) + bindings := catalog.Bindings() + bindings[0].AdapterSemverRange = ">=0.0.0" + bindings[0].Source = externalSource(toolLima) + bindings[0].Platforms[0] = "evil/platform" + bindings[0].Requirements[0].RequiredFor[0] = testShell + bindings[0].Requirements[0].ExecutableOption = "EVIL_PATH" + match, err := catalog.Match(ProviderContract{ + Source: ProviderSource{ + Kind: SourceInternal, + InternalID: toolDocker, + }, + ExecutionContract: executionDocker, + }) + s.Require().NoError(err) + match.Requirements[0].RequiredFor[0] = testShell + s.Equal("create", catalog.Bindings()[0].Requirements[0].RequiredFor[0]) + s.Equal("DOCKER_PATH", catalog.Bindings()[0].Requirements[0].ExecutableOption) + s.False(match.ManagedEligible) + s.Equal(copyCatalog.Bindings(), catalog.Bindings()) + match.ManagedEligible = true + s.True(match.ManagedEligible) + unchanged, err := catalog.Match(ProviderContract{ + Source: ProviderSource{ + Kind: SourceInternal, + InternalID: toolDocker, + }, + ExecutionContract: executionDocker, + }) + s.Require().NoError(err) + s.False(unchanged.ManagedEligible) +} diff --git a/pkg/dependencies/catalog_types.go b/pkg/dependencies/catalog_types.go new file mode 100644 index 0000000000..4375682338 --- /dev/null +++ b/pkg/dependencies/catalog_types.go @@ -0,0 +1,103 @@ +package dependencies + +type SourceKind string + +const ( + toolDocker = "docker" + toolMicrosandbox = "microsandbox" + toolApple = "apple" + toolLima = "lima" + toolOrbStack = "orbstack" + executionDocker = "internal_docker" + platformLinuxAMD64 = "linux/amd64" + platformDarwinARM64 = "darwin/arm64" + imageBackendNone = "none" + executionMicrosandbox = "external_microsandbox_v1" +) + +const ( + SourceInternal SourceKind = "internal" + SourceGitHub SourceKind = "github" + SourceURL SourceKind = "url" + SourceFile SourceKind = "file" +) + +type ProviderSource struct { + Kind SourceKind `json:"kind"` + InternalID string `json:"internalId,omitempty"` + Repository string `json:"repository,omitempty"` + Location string `json:"location,omitempty"` +} + +// ProviderContract facts must come from trusted orchestration inspecting source and full manifest, not display names. +type ProviderContract struct { + DisplayName string + Source ProviderSource + ExecutionContract string + AdapterVersion string + ManifestSHA256 string + RuntimeCheckSchema int + ImageBackend string +} + +type Requirement struct { + ToolID string `json:"toolId"` + Purpose string `json:"purpose"` + Scope string `json:"scope"` + RequiredFor []string `json:"requiredFor"` + ExecutableOption string `json:"executableOption,omitempty"` + ConfigurationOption string `json:"configurationOption,omitempty"` + ProbeID string `json:"probeId,omitempty"` + GuidanceID string `json:"guidanceId"` + WhenImageBackend string `json:"whenImageBackend,omitempty"` +} + +type Binding struct { + ID string `json:"id"` + Source ProviderSource `json:"source"` + ExecutionContract string `json:"executionContract"` + AdapterSemverRange string `json:"adapterSemverRange"` + RequiredRuntimeCheckSchema int `json:"requiredRuntimeCheckSchema"` + // Platforms describes external discovery, never managed qualification. + Platforms []string `json:"platforms"` + GuidanceID string `json:"guidanceId"` + Requirements []Requirement `json:"requirements"` +} + +type ContractMatch struct { + BindingID string + GuidanceID string + ContractVerified bool + AdapterStatus string + ManagedEligible bool + ManagedReason string + Requirements []Requirement +} + +type ArchiveMember struct { + Name string `json:"name"` + Type string `json:"type"` + MaxBytes int64 `json:"maxBytes"` +} + +type Recipe struct { + ID string `json:"id"` + ToolID string `json:"toolId"` + RuntimeVersion string `json:"runtimeVersion"` + Platform string `json:"platform"` + URL string `json:"url"` + SHA256 string `json:"sha256"` + ArchiveFormat string `json:"archiveFormat"` + Layout string `json:"layout"` + MaxArchiveBytes int64 `json:"maxArchiveBytes"` + MaxExpandedBytes int64 `json:"maxExpandedBytes"` + Members []ArchiveMember `json:"members"` + Executable string `json:"executable"` + Firmware string `json:"firmware"` + Prerequisites []string `json:"prerequisites"` + ProbeID string `json:"probeId"` + Actions []string `json:"actions"` + QualificationStatus string `json:"qualificationStatus"` + QualificationRecord string `json:"qualificationRecord"` + Enabled bool `json:"enabled"` +} diff --git a/pkg/dependencies/catalog_validate.go b/pkg/dependencies/catalog_validate.go new file mode 100644 index 0000000000..617a8e3cc7 --- /dev/null +++ b/pkg/dependencies/catalog_validate.go @@ -0,0 +1,210 @@ +package dependencies + +import ( + "errors" + "fmt" + "slices" +) + +func (d catalogDocument) validate() error { + if d.SchemaVersion != 1 || d.ID != "devsy.dependencies.catalog.v1" { + return errors.New("unsupported dependency catalog schema or identity") + } + return d.validateBindings() +} + +func (d catalogDocument) validateBindings() error { + if d.ManagedStatus != "no_qualified_recipe" || len(d.Bindings) != 7 || d.Recipes == nil { + return errors.New("incomplete or unsupported dependency catalog") + } + identities := make(map[string]bool) + for _, binding := range d.Bindings { + if identities[binding.ID] { + return fmt.Errorf("duplicate binding %q", binding.ID) + } + identities[binding.ID] = true + if err := validateBinding(binding); err != nil { + return fmt.Errorf("binding %q: %w", binding.ID, err) + } + } + return validateRecipes(d.Recipes) +} + +func validateBinding(binding Binding) error { + source, execution := bindingIdentity(binding.ID) + if execution == "" || source != binding.Source || execution != binding.ExecutionContract { + return errors.New("unrecognized source or execution contract") + } + if binding.AdapterSemverRange != "" { + return errors.New("no managed adapter range has been released and reviewed") + } + expectedSchema := 0 + if binding.ID == toolMicrosandbox { + expectedSchema = 1 + } + if binding.RequiredRuntimeCheckSchema != expectedSchema { + return errors.New("unrecognized runtime-check schema requirement") + } + if err := validateBindingPlatforms(binding); err != nil { + return err + } + return validateRequirements(binding) +} + +func bindingIdentity(id string) (ProviderSource, string) { + switch id { + case toolDocker, "podman", toolApple, "kubernetes": + return ProviderSource{Kind: SourceInternal, InternalID: id}, "internal_" + id + case toolMicrosandbox: + return externalSource(id), executionMicrosandbox + case toolLima, toolOrbStack: + return externalSource(id), id + "_exec_v1" + default: + return ProviderSource{}, "" + } +} + +func externalSource(id string) ProviderSource { + return ProviderSource{ + Kind: SourceGitHub, + Repository: "github.com/devsy-org/devsy-provider-" + id, + } +} + +func validateBindingPlatforms(binding Binding) error { + expected := []string{ + platformLinuxAMD64, + "linux/arm64", + "darwin/amd64", + platformDarwinARM64, + "windows/amd64", + "windows/arm64", + } + switch binding.ID { + case toolApple: + expected = []string{platformDarwinARM64} + case toolMicrosandbox: + expected = []string{platformLinuxAMD64, "linux/arm64", platformDarwinARM64} + case toolLima: + expected = expected[:4] + case toolOrbStack: + expected = []string{"darwin/amd64", platformDarwinARM64} + } + if !slices.Equal(binding.Platforms, expected) { + return errors.New("unsupported or duplicate binding platforms") + } + return nil +} + +func validateRequirements(binding Binding) error { + expected := []string{bindingRequirementKey(binding.ID)} + if binding.ID == toolMicrosandbox { + expected = append(expected, "docker:image_backend") + } + if len(binding.Requirements) != len(expected) { + return errors.New("missing or unexpected requirement") + } + for i, requirement := range binding.Requirements { + key := requirement.ToolID + ":" + requirement.Purpose + if key != expected[i] { + return errors.New("duplicate or unexpected requirement tool") + } + if err := validateRequirement(requirement); err != nil { + return err + } + } + if binding.GuidanceID != binding.Requirements[0].GuidanceID { + return errors.New("unrecognized binding guidance") + } + return nil +} + +func bindingRequirementKey(bindingID string) string { + switch bindingID { + case toolApple: + return "apple-container:container_runtime" + case "kubernetes": + return "kubernetes-config:cluster_configuration" + case toolMicrosandbox: + return "microsandbox:microvm_runtime" + case toolLima, toolOrbStack: + return bindingID + ":vm_runtime" + default: + return bindingID + ":container_runtime" + } +} + +type requirementContract struct { + option, configuration, probe, guidance, condition string +} + +func validateRequirement(requirement Requirement) error { + expected, ok := requirementIdentity(requirement.ToolID + ":" + requirement.Purpose) + actual := requirementContract{ + requirement.ExecutableOption, requirement.ConfigurationOption, + requirement.ProbeID, requirement.GuidanceID, requirement.WhenImageBackend, + } + if !ok || actual != expected || requirement.Scope != "controller_host" { + return errors.New("unrecognized requirement purpose, scope, option, probe or guidance") + } + if len(requirement.RequiredFor) == 0 { + return errors.New("requirement operations are required") + } + seen := make(map[string]bool) + for _, operation := range requirement.RequiredFor { + if !slices.Contains( + []string{"configure", "create", "exec", "stop", "delete", "image-build"}, + operation, + ) || + seen[operation] { + return fmt.Errorf("unrecognized or duplicate operation %q", operation) + } + seen[operation] = true + } + return nil +} + +func requirementIdentity(key string) (requirementContract, bool) { + contracts := map[string]requirementContract{ + "docker:container_runtime": { + option: "DOCKER_PATH", + probe: "docker_version", + guidance: "docker_setup", + }, + "docker:image_backend": { + probe: "docker_version", + guidance: "docker_setup", + condition: toolDocker, + }, + "podman:container_runtime": { + option: "PODMAN_PATH", + probe: "podman_version", + guidance: "podman_setup", + }, + "apple-container:container_runtime": { + option: "CONTAINER_PATH", + probe: "container_version", + guidance: "apple_container_setup", + }, + "kubernetes-config:cluster_configuration": { + configuration: "KUBERNETES_CONFIG", + guidance: "kubernetes_configuration", + }, + "microsandbox:microvm_runtime": { + probe: "microsandbox_version", + guidance: "microsandbox_setup", + }, + "lima:vm_runtime": { + option: "LIMA_PATH", + probe: "limactl_version", + guidance: "lima_setup", + }, + "orbstack:vm_runtime": { + option: "ORBSTACK_PATH", + probe: "orbctl_version", + guidance: "orbstack_setup", + }, + } + contract, ok := contracts[key] + return contract, ok +} diff --git a/pkg/dependencies/catalog_validation_test.go b/pkg/dependencies/catalog_validation_test.go new file mode 100644 index 0000000000..22691dcd16 --- /dev/null +++ b/pkg/dependencies/catalog_validation_test.go @@ -0,0 +1,239 @@ +package dependencies + +import ( + "encoding/json" + "strings" +) + +func (s *catalogSuite) TestStrictCatalogJSON() { + cases := map[string][2]string{ + "unknown top level": {`"schemaVersion": 1`, `"schemaVersion": 1, "postinstall": "sh"`}, + "unknown nested": {`"kind": "internal"`, `"kind": "internal", "shell": "curl"`}, + "duplicate key": {`"schemaVersion": 1`, `"schemaVersion": 2, "schemaVersion": 1`}, + "duplicate nested key": {`"kind": "internal"`, `"kind": "file", "kind": "internal"`}, + "null metadata": {`"adapterSemverRange": ""`, `"adapterSemverRange": null`}, + } + for name, fields := range cases { + s.Run(name, func() { + data := strings.Replace(embeddedCatalog, fields[0], fields[1], 1) + s.Require().True(json.Valid([]byte(data))) + _, err := decodeCatalog([]byte(data)) + s.Error(err) + }) + } + for _, data := range []string{embeddedCatalog + `{}`, embeddedCatalog + `garbage`, `null`} { + _, err := decodeCatalog([]byte(data)) + s.Error(err) + } +} + +func (s *catalogSuite) TestInvalidCatalogMetadata() { + cases := map[string]func(*catalogDocument){ + "schema": func(d *catalogDocument) { d.SchemaVersion = 2 }, + "identity": func(d *catalogDocument) { d.ID = testCustom }, + "managed status": func(d *catalogDocument) { d.ManagedStatus = "qualified" }, + "missing recipes": func(d *catalogDocument) { d.Recipes = nil }, + "missing binding": func(d *catalogDocument) { d.Bindings = d.Bindings[:1] }, + "duplicate binding": func(d *catalogDocument) { d.Bindings[1] = d.Bindings[0] }, + "custom binding": func(d *catalogDocument) { d.Bindings[0].ID = testCustom }, + "source kind": func(d *catalogDocument) { d.Bindings[0].Source.Kind = SourceGitHub }, + "source spoof": func(d *catalogDocument) { d.Bindings[4].Source.Repository += "-evil" }, + "adapter range": func(d *catalogDocument) { d.Bindings[4].AdapterSemverRange = ">=0.1.11" }, + "runtime schema": func(d *catalogDocument) { d.Bindings[4].RequiredRuntimeCheckSchema = 2 }, + "execution": func(d *catalogDocument) { d.Bindings[4].ExecutionContract = testShell }, + "platform": func(d *catalogDocument) { d.Bindings[0].Platforms[0] = "plan9/amd64" }, + "apple platform": func(d *catalogDocument) { d.Bindings[2].Platforms = []string{platformLinuxAMD64} }, + "guidance": func(d *catalogDocument) { d.Bindings[0].GuidanceID = "curl_install" }, + "missing requirement": func(d *catalogDocument) { d.Bindings[0].Requirements = nil }, + "option": func(d *catalogDocument) { d.Bindings[0].Requirements[0].ExecutableOption = "SHELL" }, + "probe": func(d *catalogDocument) { d.Bindings[0].Requirements[0].ProbeID = "docker_start" }, + "operation": func(d *catalogDocument) { d.Bindings[0].Requirements[0].RequiredFor[0] = testShell }, + "scope": func(d *catalogDocument) { d.Bindings[5].Requirements[0].Scope = "guest" }, + "purpose": func(d *catalogDocument) { d.Bindings[5].Requirements[0].Purpose = "container_runtime" }, + "kubernetes exec": func(d *catalogDocument) { d.Bindings[3].Requirements[0].ProbeID = "exec_auth" }, + } + for name, mutate := range cases { + s.Run(name, func() { + document := s.catalogDocument() + mutate(&document) + data, err := json.Marshal(document) + s.Require().NoError(err) + _, err = decodeCatalog(data) + s.Error(err) + }) + } +} + +func (s *catalogSuite) TestSourceRecordedRecipeIsDisabledAndCopied() { + document := s.catalogDocument() + document.Recipes = []Recipe{sourceRecordedCandidate()} + data, err := json.Marshal(document) + s.Require().NoError(err) + catalog, err := decodeCatalog(data) + s.Require().NoError(err) + recipes := catalog.Recipes() + s.Require().Len(recipes, 1) + s.False(recipes[0].Enabled) + s.Equal("v0.7.7", recipes[0].RuntimeVersion) + s.Equal("source_recorded_unqualified", recipes[0].QualificationStatus) + recipes[0].Enabled = true + recipes[0].Members[0].Name = "../msb" + recipes[0].Prerequisites[0] = imageBackendNone + recipes[0].Actions[0] = testShell + s.Equal(document.Recipes, catalog.Recipes()) + match, err := catalog.Match(ProviderContract{ + Source: externalSource( + toolMicrosandbox, + ), + ExecutionContract: executionMicrosandbox, + AdapterVersion: "v0.1.11", + }) + s.Require().NoError(err) + s.False(match.ManagedEligible) +} + +func (s *catalogSuite) TestInvalidRecipes() { + for name, mutate := range invalidRecipeCases() { + s.Run(name, func() { + document := s.catalogDocument() + recipe := sourceRecordedCandidate() + mutate(&recipe) + document.Recipes = []Recipe{recipe} + data, err := json.Marshal(document) + s.Require().NoError(err) + _, err = decodeCatalog(data) + s.Error(err) + }) + } +} + +func (s *catalogSuite) TestRecipeCannotProvideCustomInstructions() { + document := s.catalogDocument() + document.Recipes = []Recipe{sourceRecordedCandidate()} + data, err := json.Marshal(document) + s.Require().NoError(err) + modified := strings.Replace( + string(data), + `"enabled":false`, + `"enabled":false,"postinstall":["sh"]`, + 1, + ) + s.Require().NotEqual(string(data), modified) + _, err = decodeCatalog([]byte(modified)) + s.ErrorContains(err, "unknown field") +} + +func invalidRecipeCases() map[string]func(*Recipe) { + return map[string]func(*Recipe){ + "enabled": func(r *Recipe) { r.Enabled = true }, + "identity": func(r *Recipe) { r.ID = "../custom" }, + "tool": func(r *Recipe) { r.ToolID = toolDocker }, + "platform": func(r *Recipe) { r.Platform = "linux/arm64" }, + "unknown platform": func(r *Recipe) { r.Platform = "plan9/amd64" }, + "runtime version": func(r *Recipe) { r.RuntimeVersion = "latest" }, + "digest absent": func(r *Recipe) { r.SHA256 = "" }, + "digest short": func(r *Recipe) { r.SHA256 = "b3cc4a5e" }, + "digest nonhex": func(r *Recipe) { r.SHA256 = strings.Repeat("g", 64) }, + "digest prefixed": func(r *Recipe) { r.SHA256 = "sha256:" + r.SHA256 }, + "archive": func(r *Recipe) { r.ArchiveFormat = "exe" }, + "layout": func(r *Recipe) { r.Layout = "bin_lib_links" }, + "zero archive size": func(r *Recipe) { r.MaxArchiveBytes = 0 }, + "unbounded archive": func(r *Recipe) { r.MaxArchiveBytes = maxCatalogArchiveBytes + 1 }, + "negative expanded size": func(r *Recipe) { r.MaxExpandedBytes = -1 }, + "unbounded expanded size": func(r *Recipe) { r.MaxExpandedBytes = maxCatalogArchiveBytes + 1 }, + "missing member": func(r *Recipe) { r.Members = r.Members[:1] }, + "duplicate member": func(r *Recipe) { r.Members[1] = r.Members[0] }, + "traversal": func(r *Recipe) { r.Members[0].Name = "../msb" }, + "absolute member": func(r *Recipe) { r.Members[0].Name = "/msb" }, + "nested member": func(r *Recipe) { r.Members[0].Name = "bin/msb" }, + "symlink": func(r *Recipe) { r.Members[0].Type = "symlink" }, + "hardlink": func(r *Recipe) { r.Members[0].Type = "hardlink" }, + "zero member size": func(r *Recipe) { r.Members[0].MaxBytes = 0 }, + "unbounded member": func(r *Recipe) { r.Members[0].MaxBytes = maxCatalogArchiveBytes + 1 }, + "total member size": func(r *Recipe) { r.Members[1].MaxBytes = r.MaxExpandedBytes }, + "firmware": func(r *Recipe) { r.Firmware = "libkrunfw.so" }, + "executable": func(r *Recipe) { r.Executable = "sh" }, + "probe": func(r *Recipe) { r.ProbeID = "runtime_start" }, + "prerequisites": func(r *Recipe) { r.Prerequisites = []string{testShell} }, + "action": func(r *Recipe) { r.Actions = []string{"curl | sh"} }, + "qualification": func(r *Recipe) { r.QualificationStatus = "qualified" }, + "qualification record": func(r *Recipe) { r.QualificationRecord = "synthetic-evidence" }, + } +} + +func (s *catalogSuite) TestUnsafeRecipeURLs() { + base := sourceRecordedCandidate() + urls := []string{ + strings.Replace(base.URL, "https:", "http:", 1), + strings.Replace(base.URL, "github.com", "github.com.evil", 1), + strings.Replace(base.URL, "github.com", "user:password@github.com", 1), + strings.Replace(base.URL, "github.com", "github.com:443", 1), + strings.Replace(base.URL, "superradcompany", "evil", 1), + strings.Replace(base.URL, "/v0.7.7/", "/latest/", 1), + strings.Replace(base.URL, "/v0.7.7/", "/main/", 1), + strings.Replace(base.URL, "/v0.7.7/", "/v0.7.8/", 1), + strings.Replace(base.URL, "microsandbox-linux", "microsandbox%2flinux", 1), + base.URL + "?token=secret", base.URL + "?", base.URL + "#fragment", base.URL + "/suffix", + "https://github.com/superradcompany/microsandbox/releases/download/v0.7.7/install.sh", + } + for _, assetURL := range urls { + recipe := base + recipe.URL = assetURL + s.Error(validateRecipe(recipe), assetURL) + } +} + +func (s *catalogSuite) TestDuplicateRecipeIdentities() { + for _, field := range []string{"id", "tuple", "url", "digest"} { + a := sourceRecordedCandidate() + b := sourceRecordedCandidate() + b.ID = "second" + b.RuntimeVersion = "v0.7.8" + b.URL = strings.Replace(b.URL, "v0.7.7", b.RuntimeVersion, 1) + b.SHA256 = strings.Repeat("a", 64) + switch field { + case "id": + b.ID = a.ID + case "tuple": + b.RuntimeVersion = a.RuntimeVersion + case "url": + b.URL = a.URL + case "digest": + b.SHA256 = a.SHA256 + } + s.Error(validateRecipes([]Recipe{a, b}), field) + } +} + +func (s *catalogSuite) catalogDocument() catalogDocument { + var document catalogDocument + s.Require().NoError(json.Unmarshal([]byte(embeddedCatalog), &document)) + return document +} + +// Source-recorded SPEC 9.2 candidate only; these tests neither download nor qualify this artifact. +func sourceRecordedCandidate() Recipe { + return Recipe{ + ID: "microsandbox-0.7.7-linux-amd64", + ToolID: toolMicrosandbox, + RuntimeVersion: "v0.7.7", + Platform: platformLinuxAMD64, + URL: "https://github.com/superradcompany/microsandbox/releases/download/" + + "v0.7.7/microsandbox-linux-x86_64.tar.gz", + SHA256: "b3cc4a5e3f52dfdd938a6f67ac4a9a959ddfe304bab56de4964044b8613f01bb", + ArchiveFormat: "tar.gz", + Layout: "flat_verbatim_no_links", + MaxArchiveBytes: 1 << 29, + MaxExpandedBytes: 1 << 30, + Members: []ArchiveMember{ + {Name: "msb", Type: "regular", MaxBytes: 1 << 29}, + {Name: "libkrunfw.so.5.6.1", Type: "regular", MaxBytes: 1 << 29}, + }, + Executable: "msb", + Firmware: "libkrunfw.so.5.6.1", + Prerequisites: []string{"kvm"}, + ProbeID: "microsandbox_version", + Actions: []string{"install", "select", "remove"}, + QualificationStatus: "source_recorded_unqualified", + } +} diff --git a/pkg/dependencies/contracts_test.go b/pkg/dependencies/contracts_test.go new file mode 100644 index 0000000000..ad387fd3bf --- /dev/null +++ b/pkg/dependencies/contracts_test.go @@ -0,0 +1,4190 @@ +package dependencies_test + +import ( + "bytes" + "encoding/json" + "fmt" + "io" + "io/fs" + "maps" + "os" + "path/filepath" + "reflect" + "slices" + "strings" + "testing" + "time" + "unicode/utf8" + + "github.com/blang/semver/v4" + "github.com/devsy-org/devsy/pkg/clierr" + "github.com/devsy-org/devsy/pkg/config" + devcconfig "github.com/devsy-org/devsy/pkg/devcontainer/config" + "github.com/devsy-org/devsy/pkg/exitcode" + "github.com/devsy-org/devsy/pkg/status" + "github.com/stretchr/testify/suite" +) + +const ( + reportSchemaID = "devsy.dependencies.report.v1" + reportSchemaVersion = 1 + flatArchiveLayoutPolicy = "flat_verbatim_no_links" + + keywordDefs = "$defs" + keywordRef = "$ref" + keywordType = "type" + keywordConst = "const" + keywordEnum = "enum" + keywordMinLength = "minLength" + keywordMinItems = "minItems" + keywordProperties = "properties" + keywordItems = "items" + + schemaTypeObject = "object" + schemaTypeArray = "array" + schemaTypeString = "string" + schemaTypeInteger = "integer" + schemaTypeBoolean = "boolean" + + canonicalMicroSandboxRepo = "github.com/devsy-org/devsy-provider-microsandbox" + canonicalLimaRepo = "github.com/devsy-org/devsy-provider-lima" + canonicalOrbStackRepo = "github.com/devsy-org/devsy-provider-orbstack" + + providerMicroSandbox = "microsandbox" + providerDocker = "docker" + providerPodman = "podman" + providerApple = "apple" + providerKubernetes = "kubernetes" + providerSSH = "ssh" + providerTypeExternal = "external" + contextKeyProvider = "provider" + + osLinux = "linux" + osDarwin = "darwin" + osWindows = "windows" + + archAMD64 = "amd64" + archARM64 = "arm64" + + capKVMAvailable = "kvm_available" + capKVMUnavailable = "kvm_unavailable" + capHypervisorFramework = "hypervisor_framework" + capNotRequired = "not_required" + capUnsupported = "unsupported" + + qualNotRun = "not_run" + qualBlocked = "blocked" + qualQualified = "qualified" + + gateG01 = "G01" + gateG02 = "G02" + gateG03 = "G03" + gateG04 = "G04" + gateG05 = "G05" + gateG06 = "G06" + gateG07 = "G07" + gateG08 = "G08" + gateG09 = "G09" + + fixtureMissing = "report_missing.json" + fixtureExternal = "report_external.json" + fixtureIncompletePair = "report_incomplete_pair.json" + fixtureManagedDisabled = "report_managed_disabled_candidate.json" + fixtureUnsupportedHost = "report_unsupported_host.json" + fixtureStoppedRuntime = "report_stopped_runtime.json" + fixtureStaleTarget = "report_stale_target.json" + fixtureUnknownCustom = "report_unknown_custom_source.json" + fixtureConfigConflict = "report_configuration_conflict.json" + fixtureOfflineMissing = "report_offline_asset_missing.json" +) + +type surveyMode string + +const ( + surveyModePassive surveyMode = "passive" + surveyModeActiveProbe surveyMode = "active_probe" +) + +type availabilityState string + +const ( + availabilityAvailable availabilityState = "available" + availabilityMissing availabilityState = "missing" + availabilityIncomplete availabilityState = "incomplete" + availabilityUnknown availabilityState = "unknown" +) + +type compatibilityState string + +const ( + compatibilityCompatible compatibilityState = "compatible" + compatibilityIncompatible compatibilityState = "incompatible" + compatibilityUnknown compatibilityState = "unknown" +) + +type reachabilityState string + +const ( + reachabilityReachable reachabilityState = "reachable" + reachabilityUnreachable reachabilityState = "unreachable" + reachabilityNotChecked reachabilityState = "not_checked" + reachabilityNotApplicable reachabilityState = "not_applicable" +) + +type policyState string + +const ( + policyExternalOnly policyState = "external_only" + policyManagedAllowed policyState = "managed_allowed" + policyManagedSelected policyState = "managed_selected" + policyUnmanagedCustomSource policyState = "unmanaged_custom_source" + policyUnsupported policyState = "unsupported" +) + +type reasonCode string + +const ( + reasonReady reasonCode = "dependency_ready" + reasonMissing reasonCode = "dependency_missing" + reasonIncomplete reasonCode = "dependency_incomplete" + reasonPathInvalid reasonCode = "dependency_path_invalid" + reasonVersionIncompatible reasonCode = "dependency_version_incompatible" + reasonVersionUnknown reasonCode = "dependency_version_unknown" + reasonPlatformUnsupported reasonCode = "dependency_platform_unsupported" + reasonPolicyBlocked reasonCode = "dependency_policy_blocked" + reasonRuntimeUnreachable reasonCode = "dependency_runtime_unreachable" + reasonAuthRequired reasonCode = "dependency_auth_required" + reasonProbeTimeout reasonCode = "dependency_probe_timeout" + reasonIntegrityFailed reasonCode = "dependency_integrity_failed" + reasonStoreUnwritable reasonCode = "dependency_store_unwritable" + reasonRecipeUnqualified reasonCode = "dependency_recipe_unqualified" + reasonSelectionStale reasonCode = "dependency_selection_stale" + reasonInUse reasonCode = "dependency_in_use" + reasonOperationInterrupted reasonCode = "dependency_operation_interrupted" + reasonConfigurationConflict reasonCode = "dependency_configuration_conflict" + reasonOfflineAssetMissing reasonCode = "dependency_offline_asset_missing" + reasonIndirectLauncher reasonCode = "dependency_indirect_launcher" +) + +type providerSourceKind string + +const ( + providerSourceBuiltinInternal providerSourceKind = "builtin_internal" + providerSourceCanonicalExternalRelease providerSourceKind = "canonical_external_release" + providerSourceCustomGitHub providerSourceKind = "custom_github" + providerSourceCustomLocal providerSourceKind = "custom_local" + providerSourceCustomURL providerSourceKind = "custom_url" +) + +type candidateSourceKind string + +const ( + candidateSourceExplicitOption candidateSourceKind = "explicit_option" + candidateSourceExplicitEnv candidateSourceKind = "explicit_env" + candidateSourceManagedStore candidateSourceKind = "managed_store" + candidateSourceExternalPath candidateSourceKind = "external_path" + candidateSourceWellKnownPath candidateSourceKind = "well_known_path" + candidateSourceAppBundle candidateSourceKind = "app_bundle" + candidateSourceIndirectLauncher candidateSourceKind = "indirect_launcher" +) + +type actionKind string + +const ( + actionInstall actionKind = "install" + actionRepair actionKind = "repair" + actionSelect actionKind = "select" + actionRemove actionKind = "remove" + actionOpenDocs actionKind = "open_docs" +) + +type targetIdentity struct { + ContextName string `json:"contextName"` + ProviderName string `json:"providerName"` + ProviderType string `json:"providerType"` + ProviderSourceID string `json:"providerSourceId"` + ProviderSourceKind providerSourceKind `json:"providerSourceKind"` + AdapterVersion string `json:"adapterVersion,omitempty"` + TrustedBuiltinIdentity bool `json:"trustedBuiltinIdentity"` + ConfigRevision string `json:"configRevision"` + ProviderConfigRevision string `json:"providerConfigRevision"` + StaleAgainstRevision string `json:"staleAgainstRevision,omitempty"` + EvaluatedAt string `json:"evaluatedAt"` +} + +type hostIdentity struct { + GOOS string `json:"goos"` + GOARCH string `json:"goarch"` + OSVersion string `json:"osVersion,omitempty"` + VirtualizationCapability string `json:"virtualizationCapability"` +} + +type managedRecipeStatus struct { + RecipeID string `json:"recipeId"` + Tuple string `json:"tuple"` + CandidateVersion string `json:"candidateVersion,omitempty"` + IllustrativeBundleRoot string `json:"illustrativeBundleRoot,omitempty"` + Enabled bool `json:"enabled"` + QualificationState string `json:"qualificationState"` + BlockingGates []string `json:"blockingGates"` + ArchiveLayout string `json:"archiveLayout"` + ExpectedFiles []string `json:"expectedFiles"` +} + +type selectedMicroSandboxPair struct { + MSBLexicalPath string `json:"msbLexicalPath"` + MSBResolvedPath string `json:"msbResolvedPath"` + LibkrunfwLexicalPath string `json:"libkrunfwLexicalPath"` + LibkrunfwResolvedPath string `json:"libkrunfwResolvedPath"` + SourceKind candidateSourceKind `json:"sourceKind"` +} + +type candidateFileObservation struct { + FileIdentity string `json:"fileIdentity"` + Platform string `json:"platform,omitempty"` + ObservedVersion string `json:"observedVersion,omitempty"` +} + +type candidateObservation struct { + Component string `json:"component"` + SourceKind candidateSourceKind `json:"sourceKind"` + OptionName string `json:"optionName,omitempty"` + LexicalPath string `json:"lexicalPath"` + ResolvedPath string `json:"resolvedPath"` + IsSymlink bool `json:"isSymlink,omitempty"` + Observation *candidateFileObservation `json:"observation,omitempty"` + Executed bool `json:"executed"` + Selected bool `json:"selected"` + Availability availabilityState `json:"availability"` + Compatibility compatibilityState `json:"compatibility"` + ReasonCode reasonCode `json:"reasonCode"` + Detail string `json:"detail,omitempty"` +} + +type dependencyItemReport struct { + ID string `json:"id"` + DisplayName string `json:"displayName"` + Required bool `json:"required"` + Executed bool `json:"executed"` + Availability availabilityState `json:"availability"` + Compatibility compatibilityState `json:"compatibility"` + Reachability reachabilityState `json:"reachability"` + Policy policyState `json:"policy"` + ReasonCode reasonCode `json:"reasonCode"` + SelectedPair *selectedMicroSandboxPair `json:"selectedPair,omitempty"` + Candidates []candidateObservation `json:"candidates"` +} + +type remediationAction struct { + Kind actionKind `json:"kind"` + Label string `json:"label"` + Enabled bool `json:"enabled"` + DisabledReasonCode reasonCode `json:"disabledReasonCode,omitempty"` + RequiresEffectAuthorization bool `json:"requiresEffectAuthorization"` + RequiresConfirmation bool `json:"requiresConfirmation"` + CLICommand string `json:"cliCommand,omitempty"` +} + +type reportContract struct { + Schema string `json:"schema"` + SchemaVersion int `json:"schemaVersion"` + SurveyMode surveyMode `json:"surveyMode"` + Executed bool `json:"executed"` + Target targetIdentity `json:"target"` + Host hostIdentity `json:"host"` + Availability availabilityState `json:"availability"` + Compatibility compatibilityState `json:"compatibility"` + Reachability reachabilityState `json:"reachability"` + Policy policyState `json:"policy"` + ReasonCode reasonCode `json:"reasonCode"` + Message string `json:"message"` + Hint string `json:"hint,omitempty"` + ManagedRecipe *managedRecipeStatus `json:"managedRecipe,omitempty"` + Items []dependencyItemReport `json:"items"` + Actions []remediationAction `json:"actions"` +} + +type canonicalAdapterBaseline struct { + maxPublishedVersion semver.Version + supportsPathPairRuntimeCheck bool +} + +type canonicalSourceSpec struct { + repo string + tag string + ver semver.Version +} + +type targetContext struct { + report *reportContract + isCanonicalMSB bool + adapterSupportsT08 bool +} + +type dimensionSet struct { + mode surveyMode + executed bool + avail availabilityState + compat compatibilityState + reach reachabilityState + policy policyState + reason reasonCode +} + +type jsonSchemaNode struct { + Schema string `json:"$schema"` + ID string `json:"$id"` + Title string `json:"title"` + Description string `json:"description"` + Type string `json:"type"` + Ref string `json:"$ref"` + Const any `json:"const"` + Enum []string `json:"enum"` + MinLength int `json:"minLength"` + MinItems int `json:"minItems"` + AdditionalProperties *bool `json:"additionalProperties"` + Required []string `json:"required"` + Properties map[string]jsonSchemaNode `json:"properties"` + Items *jsonSchemaNode `json:"items"` + Defs map[string]jsonSchemaNode `json:"$defs"` +} + +type rawShapeCase struct { + name string + base []byte + mutate func(doc map[string]any) + errSub string +} + +type nestedCandidateMutationCase struct { + name string + mutate func(r *reportContract) + errSub string + expectSchemaErr bool +} + +type schemaKeywordMutationCase struct { + name string + mutate func(doc map[string]any) + errSub string +} + +type schemaLiteralCase struct { + name string + schema string + input string + errSub string +} + +type contractsSuite struct { + suite.Suite + contractsDir string + schema *jsonSchemaNode +} + +var ( + allowedSchemaNodeKeywords = []string{ + "$schema", + "$id", + "title", + "description", + keywordDefs, + keywordRef, + keywordType, + keywordConst, + keywordEnum, + keywordMinLength, + keywordMinItems, + "additionalProperties", + "required", + keywordProperties, + keywordItems, + } + schemaMetadataKeywords = []string{"$schema", "$id", "title", "description"} + // schemaKeywordsByType lists the only validation keywords validateSchemaValue + // evaluates for each type; anything else would be accepted but ignored. + schemaKeywordsByType = map[string][]string{ + schemaTypeObject: {"additionalProperties", "required", keywordProperties}, + schemaTypeArray: {keywordMinItems, keywordItems}, + schemaTypeString: {keywordConst, keywordEnum, keywordMinLength}, + schemaTypeInteger: {keywordConst}, + schemaTypeBoolean: {}, + } + allSurveyModes = []surveyMode{ + surveyModePassive, + surveyModeActiveProbe, + } + allAvailabilityStates = []availabilityState{ + availabilityAvailable, + availabilityMissing, + availabilityIncomplete, + availabilityUnknown, + } + allCompatibilityStates = []compatibilityState{ + compatibilityCompatible, + compatibilityIncompatible, + compatibilityUnknown, + } + allReachabilityStates = []reachabilityState{ + reachabilityReachable, + reachabilityUnreachable, + reachabilityNotChecked, + reachabilityNotApplicable, + } + allPolicyStates = []policyState{ + policyExternalOnly, + policyManagedAllowed, + policyManagedSelected, + policyUnmanagedCustomSource, + policyUnsupported, + } + allReasonCodes = []reasonCode{ + reasonReady, + reasonMissing, + reasonIncomplete, + reasonPathInvalid, + reasonVersionIncompatible, + reasonVersionUnknown, + reasonPlatformUnsupported, + reasonPolicyBlocked, + reasonRuntimeUnreachable, + reasonAuthRequired, + reasonProbeTimeout, + reasonIntegrityFailed, + reasonStoreUnwritable, + reasonRecipeUnqualified, + reasonSelectionStale, + reasonInUse, + reasonOperationInterrupted, + reasonConfigurationConflict, + reasonOfflineAssetMissing, + reasonIndirectLauncher, + } + allProviderSourceKinds = []providerSourceKind{ + providerSourceBuiltinInternal, + providerSourceCanonicalExternalRelease, + providerSourceCustomGitHub, + providerSourceCustomLocal, + providerSourceCustomURL, + } + allCandidateSourceKinds = []candidateSourceKind{ + candidateSourceExplicitOption, + candidateSourceExplicitEnv, + candidateSourceManagedStore, + candidateSourceExternalPath, + candidateSourceWellKnownPath, + candidateSourceAppBundle, + candidateSourceIndirectLauncher, + } + allActionKinds = []actionKind{ + actionInstall, + actionRepair, + actionSelect, + actionRemove, + actionOpenDocs, + } + allGateIDs = []string{ + gateG01, + gateG02, + gateG03, + gateG04, + gateG05, + gateG06, + gateG07, + gateG08, + gateG09, + } + allHostGOOS = []string{ + osLinux, + osDarwin, + osWindows, + } + allHostGOARCH = []string{ + archAMD64, + archARM64, + } + allVirtualizationCapabilities = []string{ + capKVMAvailable, + capKVMUnavailable, + capHypervisorFramework, + capNotRequired, + capUnsupported, + } + allQualificationStates = []string{ + qualNotRun, + qualBlocked, + qualQualified, + } + builtinInternalProviderTypes = []string{ + providerDocker, + providerPodman, + providerApple, + providerKubernetes, + providerSSH, + } + canonicalExternalAdapters = map[string]canonicalAdapterBaseline{ + canonicalMicroSandboxRepo: { + maxPublishedVersion: semver.MustParse("0.1.11"), + supportsPathPairRuntimeCheck: false, + }, + canonicalLimaRepo: { + maxPublishedVersion: semver.MustParse("1.1.0"), + supportsPathPairRuntimeCheck: false, + }, + canonicalOrbStackRepo: { + maxPublishedVersion: semver.MustParse("1.1.4"), + supportsPathPairRuntimeCheck: false, + }, + } +) + +func TestContractsSuite(t *testing.T) { + suite.Run(t, new(contractsSuite)) +} + +func (s *contractsSuite) SetupSuite() { + s.contractsDir = filepath.Join("testdata", "contracts") + schema, err := loadSchemaDoc(filepath.Join(s.contractsDir, "schema.json")) + s.Require().NoError(err) + s.schema = schema +} + +func (s *contractsSuite) TestSchemaAndGoContractCoherence() { + s.Equal(toStrings(allSurveyModes), s.schema.Properties["surveyMode"].Enum) + s.Equal(toStrings(allAvailabilityStates), s.schema.Defs["availabilityState"].Enum) + s.Equal(toStrings(allCompatibilityStates), s.schema.Defs["compatibilityState"].Enum) + s.Equal(toStrings(allReachabilityStates), s.schema.Defs["reachabilityState"].Enum) + s.Equal(toStrings(allPolicyStates), s.schema.Defs["policyState"].Enum) + s.Equal(toStrings(allReasonCodes), s.schema.Defs["reasonCode"].Enum) + s.Equal(toStrings(allProviderSourceKinds), s.schema.Defs["providerSourceKind"].Enum) + s.Equal(toStrings(allCandidateSourceKinds), s.schema.Defs["candidateSourceKind"].Enum) + s.Equal(toStrings(allActionKinds), s.schema.Defs["actionKind"].Enum) + s.Equal(allGateIDs, s.schema.Defs["gateId"].Enum) + s.Equal(allHostGOOS, s.schema.Defs["hostIdentity"].Properties["goos"].Enum) + s.Equal(allHostGOARCH, s.schema.Defs["hostIdentity"].Properties["goarch"].Enum) + s.Equal( + allVirtualizationCapabilities, + s.schema.Defs["hostIdentity"].Properties["virtualizationCapability"].Enum, + ) + s.Equal( + allQualificationStates, + s.schema.Defs["managedRecipeStatus"].Properties["qualificationState"].Enum, + ) + s.assertAllStructsMatchSchema() +} + +func (s *contractsSuite) TestCanonicalReasonCodeVocabularyAndAliasRejection() { + s.verifyIndependentCanonicalReasonVocabulary() + s.verifyRemovedReasonAliasesRejected() + s.verifyCanonicalReasonDimensionSemantics() +} + +func (s *contractsSuite) TestCandidateFileObservationIdentityAndSymlinkRecheck() { + s.verifyAvailableAndMissingCandidateObservations() + s.verifyCandidateObservationMutationsRejected() + s.verifySymlinkTargetUpdatePreservesLexicalPathWithDistinctIdentity() +} + +func (s *contractsSuite) TestSchemaLoaderRejectsUnsupportedValidationKeywords() { + s.verifyUnsupportedSchemaKeywordsRejected() +} + +func (s *contractsSuite) TestSchemaExactIntegerAndUnicodeLengthConstraints() { + for _, tc := range buildInexactIntegerSchemaLiteralCases() { + s.Run(tc.name, func() { + _, err := parseSchemaBytes([]byte(tc.schema)) + s.Require().ErrorContains(err, tc.errSub) + }) + } + cases := slices.Concat( + buildExactIntegerValidationLiteralCases(), + buildUnicodeMinLengthLiteralCases(), + ) + for _, tc := range cases { + s.Run(tc.name, func() { + parsed, err := parseSchemaBytes([]byte(tc.schema)) + s.Require().NoError(err) + err = validateRawJSONAgainstSchema([]byte(tc.input), parsed) + if tc.errSub == "" { + s.Require().NoError(err) + return + } + s.Require().ErrorContains(err, tc.errSub) + }) + } +} + +func (s *contractsSuite) TestValidFixturesAndScenarioInvariants() { + s.verifyCoreFixtures() + s.verifyLifecycleAndConflictFixtures() +} + +func (s *contractsSuite) TestRejectsRawJSONShapeViolations() { + managedRaw := s.readRawFixture(fixtureManagedDisabled) + staleRaw := s.readRawFixture(fixtureStaleTarget) + + for _, tc := range buildRootAndRecipeDeletionCases(managedRaw) { + s.runRawShapeCase(tc) + } + for _, tc := range buildItemAndActionDeletionCases(managedRaw, staleRaw) { + s.runRawShapeCase(tc) + } + for _, tc := range buildTypeAndUnknownFieldCases(managedRaw) { + s.runRawShapeCase(tc) + } + s.verifyTrailingJSONRejected(managedRaw) +} + +func (s *contractsSuite) TestRejectsMalformedOrMissingIdentity() { + base := s.loadFixture(fixtureMissing) + cases := []struct { + name string + mutate func(r *reportContract) + errSub string + }{ + { + name: "missing contextName", + mutate: func(r *reportContract) { r.Target.ContextName = "" }, + errSub: "target.contextName is required", + }, + { + name: "missing providerName", + mutate: func(r *reportContract) { r.Target.ProviderName = " " }, + errSub: "target.providerName is required", + }, + { + name: "missing providerSourceId", + mutate: func(r *reportContract) { r.Target.ProviderSourceID = "" }, + errSub: "target.providerSourceId is required", + }, + { + name: "missing providerConfigRevision", + mutate: func(r *reportContract) { r.Target.ProviderConfigRevision = "" }, + errSub: "target.providerConfigRevision is required", + }, + { + name: "invalid host goos", + mutate: func(r *reportContract) { r.Host.GOOS = "freebsd" }, + errSub: "invalid host.goos", + }, + } + + for _, tc := range cases { + s.Run(tc.name, func() { + clone := cloneReport(s.T(), base) + tc.mutate(clone) + s.Require().ErrorContains(validateReportContract(clone), tc.errSub) + }) + } +} + +func (s *contractsSuite) TestRejectsMalformedNestedEnumsAndMissingCandidateIdentity() { + stale := s.loadFixture(fixtureStaleTarget) + cases := slices.Concat( + buildNestedEnumMutationCases(), + buildMissingCandidateIdentityCases(), + ) + for _, tc := range cases { + s.Run(tc.name, func() { + clone := cloneReport(s.T(), stale) + tc.mutate(clone) + s.Require().ErrorContains(validateReportContract(clone), tc.errSub) + + raw, err := json.Marshal(clone) + s.Require().NoError(err) + if tc.expectSchemaErr { + s.Require().Error(validateRawJSONAgainstSchema(raw, s.schema)) + } + }) + } +} + +func (s *contractsSuite) TestRejectsInconsistentStoppedVsMissing() { + stopped := s.loadFixture(fixtureStoppedRuntime) + + relabeledMissing := cloneReport(s.T(), stopped) + relabeledMissing.Availability = availabilityMissing + s.Require().ErrorContains( + validateReportContract(relabeledMissing), + "stopped/unreachable runtime must report availability=\"available\"", + ) + + passiveUnreachable := cloneReport(s.T(), stopped) + passiveUnreachable.SurveyMode = surveyModePassive + passiveUnreachable.Executed = false + s.Require().ErrorContains( + validateReportContract(passiveUnreachable), + "passive survey must not report reachability=\"unreachable\"", + ) + + missingWithUnreachableReason := s.loadFixture(fixtureMissing) + missingWithUnreachableReason.ReasonCode = reasonRuntimeUnreachable + s.Require().ErrorContains( + validateReportContract(missingWithUnreachableReason), + "stopped/unreachable runtime must report availability=\"available\"", + ) +} + +func (s *contractsSuite) TestCanonicalSourceSemverCrossAdapterSpoofingAndAliases() { + s.Run("custom source spoofing built-in name rejected", s.verifyCustomSpoofingRejected) + s.Run("canonical source with bad semver tag rejected", s.verifyBadCanonicalSemverRejected) + s.Run("synthetic future adapter release tag rejected", s.verifySyntheticFutureTagRejected) + s.Run("incoherent adapterVersion or providerType rejected", s.verifyIncoherentTargetRejected) + s.Run("cross-adapter spoofing with Lima or OrbStack rejected", s.verifyCrossAdapterSpoofing) + s.Run("legitimate renamed MicroSandbox alias accepted", func() { + renamed := s.loadFixture(fixtureManagedDisabled) + renamed.Target.ProviderName = "msb-work-alias" + s.Require().NoError(validateReportContract(renamed)) + }) +} + +func (s *contractsSuite) TestRejectsV0111EligibilityAndUnqualifiedManagedActivation() { + managed := s.loadFixture(fixtureManagedDisabled) + + s.Run("managed_selected policy on v0.1.11 rejected", func() { + selectedPolicy := cloneReport(s.T(), managed) + selectedPolicy.Policy = policyManagedSelected + s.Require().ErrorContains( + validateReportContract(selectedPolicy), + "not eligible for policy=\"managed_selected\"", + ) + }) + s.Run("compatible claim on v0.1.11 in active_probe rejected", func() { + s.verifyActiveProbeCompatibleOnV0111Rejected(managed) + }) + s.Run("enabled or qualified recipe rejected", func() { + s.verifyEnabledOrQualifiedRecipeRejected(managed) + }) + s.Run("enabled install or select action on v0.1.11 rejected", func() { + s.verifyEnabledActionsOnV0111Rejected(managed) + }) + s.Run("mutating action without effect authorization rejected", func() { + unauthorized := cloneReport(s.T(), managed) + unauthorized.Actions[0].RequiresEffectAuthorization = false + s.Require().ErrorContains( + validateReportContract(unauthorized), + "must set requiresEffectAuthorization=true", + ) + }) +} + +func (s *contractsSuite) TestBundleRelativeFlatLayoutAndLinkInvariants() { + managed := s.loadFixture(fixtureManagedDisabled) + + s.Run("legitimate DEVSY_HOME ancestors named bin and lib are accepted", func() { + s.verifyAncestorBinLibAccepted(managed) + }) + s.Run("nested bundle subdirectories under illustrativeBundleRoot rejected", func() { + s.verifyNestedBundleSubdirsRejected(managed) + }) + s.Run("non-flat expectedFiles entries rejected", func() { + for _, badExpected := range []string{"bin/msb", "lib/libkrunfw.so.5.6.1", ".", "..", "../msb"} { + bad := cloneReport(s.T(), managed) + bad.ManagedRecipe.ExpectedFiles = []string{badExpected} + s.Require().Error(validateReportContract(bad)) + } + }) + s.Run("dot and parent traversal segments rejected", func() { + s.verifyTraversalSegmentsRejected(managed) + }) + s.Run("symlink flag or indirect launcher selection rejected", func() { + s.verifySymlinkAndShimRejected(managed) + }) +} + +func (s *contractsSuite) TestOfflineAssetMissingAndConfigurationConflictSemantics() { + conflict := s.loadFixture(fixtureConfigConflict) + offlineMissing := s.loadFixture(fixtureOfflineMissing) + + s.Run("offline_asset_missing rejected on available or external Docker candidate", func() { + falseOfflineOnDocker := cloneReport(s.T(), conflict) + falseOfflineOnDocker.Items[0].Candidates[1].ReasonCode = reasonOfflineAssetMissing + s.Require().ErrorContains( + validateReportContract(falseOfflineOnDocker), + "valid only for missing managed_store candidates on canonical MicroSandbox targets", + ) + }) + s.Run("offline_asset_missing rejected on available managed_store candidate", func() { + availableOffline := cloneReport(s.T(), offlineMissing) + availableOffline.Items[0].Candidates[0].Availability = availabilityAvailable + availableOffline.Items[0].Candidates[0].ResolvedPath = availableOffline.Items[0].Candidates[0].LexicalPath + availableOffline.Items[0].Candidates[0].Observation = &candidateFileObservation{ + FileIdentity: "illustrative-fid:linux-amd64:msb-store-01", + Platform: "linux/amd64", + } + s.Require().ErrorContains( + validateReportContract(availableOffline), + "valid only for missing managed_store candidates", + ) + }) + s.Run("offline_asset_missing rejected when install action is enabled", func() { + enabledOfflineInstall := cloneReport(s.T(), offlineMissing) + enabledOfflineInstall.Actions[0].Enabled = true + s.Require().ErrorContains( + validateReportContract(enabledOfflineInstall), + "cannot be enabled while all recipes remain unqualified", + ) + }) + s.Run("configuration_conflict rejected if a conflicting candidate is marked selected", func() { + selectedConflict := cloneReport(s.T(), conflict) + selectedConflict.Items[0].Candidates[1].Selected = true + s.Require().ErrorContains( + validateReportContract(selectedConflict), + "configuration conflict item must not select candidate", + ) + }) + s.Run("unexecuted candidate cannot claim compatible in passive or active reports", func() { + s.verifyUnexecutedCandidateCompatibleRejected(conflict) + }) +} + +func (s *contractsSuite) TestGateIdentitiesAndTupleSeparation() { + managed := s.loadFixture(fixtureManagedDisabled) + + s.Run("linux tuple rejects macOS G03, update G05, and Desktop skew G08 gates", func() { + for _, wrongGate := range []string{gateG03, gateG05, gateG08} { + bad := cloneReport(s.T(), managed) + bad.ManagedRecipe.BlockingGates = append( + slices.Clone(bad.ManagedRecipe.BlockingGates), + wrongGate, + ) + s.Require().Error(validateReportContract(bad)) + } + }) + s.Run("fabricated blocker ID in blockingGates rejected by both schema and validator", func() { + s.verifyFabricatedBlockerIDRejected(managed) + }) + s.Run("linux/arm64 blocked tuple uses G01/G02/G04/G06/G07/G09 and kvm_unavailable", func() { + s.verifyLinuxARM64BlockedTuple(managed) + }) + s.Run( + "darwin/arm64 candidate tuple uses G01/G02/G03/G06/G07/G09 and rejects Linux G04", + func() { + s.verifyDarwinARM64CandidateTuple(managed) + }, + ) +} + +func (s *contractsSuite) TestRejectsStaleTargetWithEnabledActionAndPassiveExecution() { + stale := s.loadFixture(fixtureStaleTarget) + stale.Actions[0].Enabled = true + s.Require().ErrorContains( + validateReportContract(stale), + "stale target report must not enable mutating action", + ) + + passiveExecuted := s.loadFixture(fixtureMissing) + passiveExecuted.Executed = true + s.Require().ErrorContains( + validateReportContract(passiveExecuted), + "passive survey must have executed=false", + ) +} + +func (s *contractsSuite) TestAllChangedFilesAreASCIIOnly() { + entries, err := os.ReadDir(s.contractsDir) + s.Require().NoError(err) + + s.assertFileIsASCIIOnly("contracts_test.go") + for _, entry := range entries { + if !entry.IsDir() { + s.assertFileIsASCIIOnly(filepath.Join(s.contractsDir, entry.Name())) + } + } +} + +func (s *contractsSuite) TestConfigSchemaVersionRemainsOne() { + s.Equal(1, config.CurrentSchemaVersion) +} + +func (s *contractsSuite) TestBaselineStatusAndErrorEnvelopes() { + s.T().Setenv("DEVSY_TEST_SECRET_TOKEN", "super-secret-token") + s.verifyBaselineStatusEnvelope() + s.verifyBaselineCLIErrorEnvelope() +} + +func (s *contractsSuite) decodeAndValidateRaw(raw []byte) (*reportContract, error) { + if err := validateRawJSONAgainstSchema(raw, s.schema); err != nil { + return nil, err + } + dec := json.NewDecoder(bytes.NewReader(raw)) + dec.DisallowUnknownFields() + + var report reportContract + if err := dec.Decode(&report); err != nil { + return nil, err + } + var extra any + if err := dec.Decode(&extra); err != io.EOF { + return nil, fmt.Errorf("unexpected trailing JSON content") + } + if err := validateReportContract(&report); err != nil { + return nil, err + } + return &report, nil +} + +func (s *contractsSuite) readRawFixture(filename string) []byte { + s.T().Helper() + raw, err := readTestFile(filepath.Join(s.contractsDir, filename)) + s.Require().NoError(err) + return raw +} + +func (s *contractsSuite) loadFixture(filename string) *reportContract { + s.T().Helper() + raw := s.readRawFixture(filename) + report, err := s.decodeAndValidateRaw(raw) + s.Require().NoError(err, "fixture %s failed schema or contract validation", filename) + return report +} + +func (s *contractsSuite) assertAllStructsMatchSchema() { + s.assertStructMatchesSchemaObject(reflect.TypeFor[reportContract](), *s.schema) + s.assertStructMatchesSchemaObject( + reflect.TypeFor[targetIdentity](), + s.schema.Defs["targetIdentity"], + ) + s.assertStructMatchesSchemaObject( + reflect.TypeFor[hostIdentity](), + s.schema.Defs["hostIdentity"], + ) + s.assertStructMatchesSchemaObject( + reflect.TypeFor[managedRecipeStatus](), + s.schema.Defs["managedRecipeStatus"], + ) + s.assertStructMatchesSchemaObject( + reflect.TypeFor[selectedMicroSandboxPair](), + s.schema.Defs["selectedMicroSandboxPair"], + ) + s.assertStructMatchesSchemaObject( + reflect.TypeFor[candidateFileObservation](), + s.schema.Defs["candidateFileObservation"], + ) + s.assertStructMatchesSchemaObject( + reflect.TypeFor[candidateObservation](), + s.schema.Defs["candidateObservation"], + ) + s.assertStructMatchesSchemaObject( + reflect.TypeFor[dependencyItemReport](), + s.schema.Defs["dependencyItemReport"], + ) + s.assertStructMatchesSchemaObject( + reflect.TypeFor[remediationAction](), + s.schema.Defs["remediationAction"], + ) +} + +func (s *contractsSuite) assertStructMatchesSchemaObject(t reflect.Type, node jsonSchemaNode) { + s.T().Helper() + structFields := make([]string, 0, t.NumField()) + requiredByStruct := make([]string, 0, t.NumField()) + for field := range t.Fields() { + tag := field.Tag.Get("json") + parts := strings.Split(tag, ",") + name := parts[0] + s.Require().NotEmpty(name) + structFields = append(structFields, name) + if !slices.Contains(parts[1:], "omitempty") { + requiredByStruct = append(requiredByStruct, name) + } + } + schemaProps := make([]string, 0, len(node.Properties)) + for k := range node.Properties { + schemaProps = append(schemaProps, k) + } + slices.Sort(structFields) + slices.Sort(schemaProps) + s.Equal(schemaProps, structFields, "struct %s fields drifted from schema.json", t.Name()) + + expectedReq := slices.Clone(node.Required) + slices.Sort(expectedReq) + slices.Sort(requiredByStruct) + s.Equal(expectedReq, requiredByStruct, "struct %s required fields drifted", t.Name()) +} + +func (s *contractsSuite) verifyCoreFixtures() { + missing := s.loadFixture(fixtureMissing) + s.Equal(surveyModePassive, missing.SurveyMode) + s.False(missing.Executed) + s.Equal(availabilityMissing, missing.Availability) + s.Equal(reachabilityNotChecked, missing.Reachability) + s.Equal(reasonMissing, missing.ReasonCode) + s.Nil(missing.Items[0].Candidates[0].Observation) + + external := s.loadFixture(fixtureExternal) + s.Equal(surveyModeActiveProbe, external.SurveyMode) + s.True(external.Executed) + s.Equal(availabilityAvailable, external.Availability) + s.Equal(compatibilityCompatible, external.Compatibility) + s.Equal(reachabilityReachable, external.Reachability) + s.Equal(reasonReady, external.ReasonCode) + s.Require().Len(external.Items[0].Candidates, 1) + s.True(external.Items[0].Candidates[0].IsSymlink) + s.Require().NotNil(external.Items[0].Candidates[0].Observation) + s.Equal( + "illustrative-fid:darwin-arm64:docker-28.0.1-cellar-9f2a", + external.Items[0].Candidates[0].Observation.FileIdentity, + ) + + incomplete := s.loadFixture(fixtureIncompletePair) + s.Equal(availabilityIncomplete, incomplete.Availability) + s.Equal(reasonIncomplete, incomplete.ReasonCode) + s.Nil(incomplete.Items[0].SelectedPair) + s.Equal(reasonIndirectLauncher, incomplete.Items[0].Candidates[0].ReasonCode) + s.False(incomplete.Items[0].Candidates[0].Selected) + s.False(incomplete.Actions[0].Enabled) + s.Equal(reasonIncomplete, incomplete.Actions[0].DisabledReasonCode) + + managed := s.loadFixture(fixtureManagedDisabled) + s.Equal(policyManagedAllowed, managed.Policy) + s.Equal(reasonRecipeUnqualified, managed.ReasonCode) + s.Require().NotNil(managed.ManagedRecipe) + s.False(managed.ManagedRecipe.Enabled) + s.Equal(qualNotRun, managed.ManagedRecipe.QualificationState) + s.Equal( + []string{gateG01, gateG02, gateG04, gateG06, gateG07, gateG09}, + managed.ManagedRecipe.BlockingGates, + ) + s.Equal(flatArchiveLayoutPolicy, managed.ManagedRecipe.ArchiveLayout) + s.False(managed.Actions[0].Enabled) +} + +func (s *contractsSuite) verifyLifecycleAndConflictFixtures() { + unsupported := s.loadFixture(fixtureUnsupportedHost) + s.Equal(osWindows, unsupported.Host.GOOS) + s.Equal(archAMD64, unsupported.Host.GOARCH) + s.Equal(capUnsupported, unsupported.Host.VirtualizationCapability) + s.Equal(policyUnsupported, unsupported.Policy) + s.Equal(reasonPlatformUnsupported, unsupported.ReasonCode) + s.Nil(unsupported.ManagedRecipe) + + stopped := s.loadFixture(fixtureStoppedRuntime) + s.Equal(surveyModeActiveProbe, stopped.SurveyMode) + s.True(stopped.Executed) + s.Equal(availabilityAvailable, stopped.Availability) + s.Equal(reachabilityUnreachable, stopped.Reachability) + s.Equal(reasonRuntimeUnreachable, stopped.ReasonCode) + + stale := s.loadFixture(fixtureStaleTarget) + s.Equal("prov-rev-msb-07", stale.Target.ProviderConfigRevision) + s.Equal("prov-rev-msb-08", stale.Target.StaleAgainstRevision) + s.Equal(compatibilityUnknown, stale.Compatibility) + s.Equal(reasonSelectionStale, stale.ReasonCode) + s.False(stale.Actions[0].Enabled) + + custom := s.loadFixture(fixtureUnknownCustom) + s.Equal(providerDocker, custom.Target.ProviderName) + s.False(custom.Target.TrustedBuiltinIdentity) + s.Equal(policyUnmanagedCustomSource, custom.Policy) + s.Equal(reasonPolicyBlocked, custom.ReasonCode) + + conflict := s.loadFixture(fixtureConfigConflict) + s.Equal(reasonConfigurationConflict, conflict.ReasonCode) + s.Equal(reasonConfigurationConflict, conflict.Items[0].Candidates[0].ReasonCode) + s.Equal(reasonConfigurationConflict, conflict.Items[0].Candidates[1].ReasonCode) + + offlineMissing := s.loadFixture(fixtureOfflineMissing) + s.Equal("msb-linux", offlineMissing.Target.ProviderName) + s.Equal(reasonOfflineAssetMissing, offlineMissing.ReasonCode) + s.Equal(reasonOfflineAssetMissing, offlineMissing.Items[0].Candidates[0].ReasonCode) + s.False(offlineMissing.Actions[0].Enabled) +} + +func (s *contractsSuite) runRawShapeCase(tc rawShapeCase) { + s.Run(tc.name, func() { + var doc map[string]any + s.Require().NoError(json.Unmarshal(tc.base, &doc)) + tc.mutate(doc) + mutatedRaw, err := json.Marshal(doc) + s.Require().NoError(err) + + _, err = s.decodeAndValidateRaw(mutatedRaw) + s.Require().ErrorContains(err, tc.errSub) + }) +} + +func (s *contractsSuite) verifyTrailingJSONRejected(managedRaw []byte) { + s.Run("trailing JSON document rejected", func() { + trailingDoc := append(slices.Clone(managedRaw), []byte("\n{}")...) + _, err := s.decodeAndValidateRaw(trailingDoc) + s.Require().ErrorContains(err, "trailing JSON content") + }) + + s.Run("trailing scalar token rejected", func() { + trailingScalar := append(slices.Clone(managedRaw), []byte(" true")...) + _, err := s.decodeAndValidateRaw(trailingScalar) + s.Require().ErrorContains(err, "trailing JSON content") + }) +} + +func (s *contractsSuite) verifyCustomSpoofingRejected() { + custom := s.loadFixture(fixtureUnknownCustom) + + spoofTrustedFlag := cloneReport(s.T(), custom) + spoofTrustedFlag.Target.ProviderName = providerMicroSandbox + spoofTrustedFlag.Target.ProviderSourceID = "github.com/attacker/devsy-provider-microsandbox@v0.1.11" + spoofTrustedFlag.Target.TrustedBuiltinIdentity = true + s.Require().ErrorContains( + validateReportContract(spoofTrustedFlag), + "must not set trustedBuiltinIdentity=true", + ) + + spoofPolicy := cloneReport(s.T(), custom) + spoofPolicy.Policy = policyManagedAllowed + s.Require().ErrorContains( + validateReportContract(spoofPolicy), + "custom provider source must use policy=\"unmanaged_custom_source\"", + ) + + spoofCanonicalKind := cloneReport(s.T(), custom) + spoofCanonicalKind.Target.ProviderSourceKind = providerSourceCanonicalExternalRelease + spoofCanonicalKind.Target.ProviderSourceID = "github.com/attacker/devsy-provider-microsandbox@v0.1.11" + spoofCanonicalKind.Target.TrustedBuiltinIdentity = true + s.Require().ErrorContains( + validateReportContract(spoofCanonicalKind), + "not an approved canonical devsy-org adapter", + ) +} + +func (s *contractsSuite) verifyBadCanonicalSemverRejected() { + managed := s.loadFixture(fixtureManagedDisabled) + for _, badSource := range []string{ + "github.com/devsy-org/devsy-provider-microsandbox@garbage", + "github.com/devsy-org/devsy-provider-microsandbox@latest", + "github.com/devsy-org/devsy-provider-microsandbox@0.1.11", + "github.com/devsy-org/devsy-provider-microsandbox@v0.1.11-rc.1", + "github.com/devsy-org/devsy-provider-microsandbox/sub@v0.1.11", + "github.com/devsy-org/devsy-provider-microsandbox@v0.1.11@extra", + } { + bad := cloneReport(s.T(), managed) + bad.Target.ProviderSourceID = badSource + s.Require().Error(validateReportContract(bad), "expected error for %s", badSource) + } +} + +func (s *contractsSuite) verifySyntheticFutureTagRejected() { + managed := s.loadFixture(fixtureManagedDisabled) + synthetic := cloneReport(s.T(), managed) + synthetic.Target.ProviderSourceID = "github.com/devsy-org/devsy-provider-microsandbox@v0.1.12" + synthetic.Target.AdapterVersion = "v0.1.12" + s.Require().ErrorContains(validateReportContract(synthetic), "unreleased synthetic version") +} + +func (s *contractsSuite) verifyIncoherentTargetRejected() { + managed := s.loadFixture(fixtureManagedDisabled) + + mismatchVer := cloneReport(s.T(), managed) + mismatchVer.Target.AdapterVersion = "v0.1.10" + s.Require().ErrorContains( + validateReportContract(mismatchVer), + "adapterVersion \"v0.1.10\" must match source tag \"v0.1.11\"", + ) + + wrongProviderType := cloneReport(s.T(), managed) + wrongProviderType.Target.ProviderType = providerMicroSandbox + s.Require().ErrorContains( + validateReportContract(wrongProviderType), + "must have providerType=\"external\"", + ) + + builtinMismatch := s.loadFixture(fixtureMissing) + builtinMismatch.Target.ProviderType = providerPodman + s.Require().ErrorContains( + validateReportContract(builtinMismatch), + "builtin_internal source must equal \"internal:podman\"", + ) +} + +func (s *contractsSuite) verifyCrossAdapterSpoofing() { + managed := s.loadFixture(fixtureManagedDisabled) + stopped := s.loadFixture(fixtureStoppedRuntime) + + limaSpoof := cloneReport(s.T(), managed) + limaSpoof.Target.ProviderName = providerMicroSandbox + limaSpoof.Target.ProviderSourceID = "github.com/devsy-org/devsy-provider-lima@v1.1.0" + limaSpoof.Target.AdapterVersion = "v1.1.0" + s.Require().ErrorContains( + validateReportContract(limaSpoof), + "restricted to canonical external microsandbox source", + ) + + orbSpoofPair := cloneReport(s.T(), stopped) + orbSpoofPair.Target.ProviderName = providerMicroSandbox + orbSpoofPair.Items[0].SelectedPair = &selectedMicroSandboxPair{ + MSBLexicalPath: "/opt/microsandbox/msb", + MSBResolvedPath: "/opt/microsandbox/msb", + LibkrunfwLexicalPath: "/opt/microsandbox/libkrunfw.so.5.6.1", + LibkrunfwResolvedPath: "/opt/microsandbox/libkrunfw.so.5.6.1", + SourceKind: candidateSourceExplicitOption, + } + s.Require().ErrorContains( + validateReportContract(orbSpoofPair), + "selectedPair is only valid for canonical MicroSandbox targets", + ) +} + +func (s *contractsSuite) verifyActiveProbeCompatibleOnV0111Rejected(managed *reportContract) { + activeCompat := cloneReport(s.T(), managed) + activeCompat.SurveyMode = surveyModeActiveProbe + activeCompat.Executed = true + activeCompat.Availability = availabilityAvailable + activeCompat.Compatibility = compatibilityCompatible + activeCompat.Reachability = reachabilityReachable + activeCompat.Policy = policyExternalOnly + activeCompat.ManagedRecipe = nil + activeCompat.ReasonCode = reasonReady + s.Require().ErrorContains( + validateReportContract(activeCompat), + "unqualified microsandbox adapter lacking T08 runtime-check support", + ) +} + +func (s *contractsSuite) verifyEnabledOrQualifiedRecipeRejected(managed *reportContract) { + enabledRecipe := cloneReport(s.T(), managed) + enabledRecipe.ManagedRecipe.Enabled = true + s.Require().ErrorContains( + validateReportContract(enabledRecipe), + "cannot be enabled before qualification gates pass", + ) + + qualifiedRecipe := cloneReport(s.T(), managed) + qualifiedRecipe.ManagedRecipe.QualificationState = qualQualified + s.Require().ErrorContains( + validateReportContract(qualifiedRecipe), + "cannot claim qualificationState=qualified in T00a baseline", + ) +} + +func (s *contractsSuite) verifyEnabledActionsOnV0111Rejected(managed *reportContract) { + enabledInstall := cloneReport(s.T(), managed) + enabledInstall.Actions[0].Enabled = true + s.Require().ErrorContains( + validateReportContract(enabledInstall), + "cannot be enabled while all recipes remain unqualified", + ) + + incomplete := s.loadFixture(fixtureIncompletePair) + incomplete.Actions[0].Enabled = true + s.Require().ErrorContains(validateReportContract(incomplete), "lacking T08 support (G01)") +} + +func (s *contractsSuite) verifyAncestorBinLibAccepted(managed *reportContract) { + bundleRoot := "/home/dev/bin/lib/devsy-home/dependencies/store/microsandbox/v0.7.7-linux-amd64" + ancestorBinLib := cloneReport(s.T(), managed) + ancestorBinLib.ManagedRecipe.IllustrativeBundleRoot = bundleRoot + ancestorBinLib.Items[0].Candidates[0].LexicalPath = bundleRoot + "/msb" + ancestorBinLib.Items[0].Candidates[1].LexicalPath = bundleRoot + "/libkrunfw.so.5.6.1" + s.Require().NoError(validateReportContract(ancestorBinLib)) +} + +func (s *contractsSuite) verifyNestedBundleSubdirsRejected(managed *reportContract) { + for _, nestedRel := range []string{"bin/msb", "lib/libkrunfw.so.5.6.1", "nested/msb"} { + nested := cloneReport(s.T(), managed) + nested.Items[0].Candidates[0].LexicalPath = + nested.ManagedRecipe.IllustrativeBundleRoot + "/" + nestedRel + s.Require().ErrorContains( + validateReportContract(nested), + "must be flat without subdirectory separators", + ) + } +} + +func (s *contractsSuite) verifyTraversalSegmentsRejected(managed *reportContract) { + for _, badPath := range []string{ + "/home/dev/.devsy/dependencies/store/microsandbox/v0.7.7-linux-amd64/./msb", + "/home/dev/.devsy/dependencies/store/microsandbox/v0.7.7-linux-amd64/../msb", + "/home/dev/.devsy/dependencies/store/../store/microsandbox/v0.7.7-linux-amd64/msb", + } { + bad := cloneReport(s.T(), managed) + bad.Items[0].Candidates[0].LexicalPath = badPath + s.Require().ErrorContains( + validateReportContract(bad), + "dot, or parent path segments", + ) + } +} + +func (s *contractsSuite) verifySymlinkAndShimRejected(managed *reportContract) { + symlinkCandidate := cloneReport(s.T(), managed) + symlinkCandidate.Items[0].Candidates[1].IsSymlink = true + s.Require().ErrorContains(validateReportContract(symlinkCandidate), "must not be a symlink") + + incomplete := s.loadFixture(fixtureIncompletePair) + selectedShim := cloneReport(s.T(), incomplete) + selectedShim.Items[0].Candidates[0].Selected = true + s.Require().ErrorContains(validateReportContract(selectedShim), "indirect launcher candidate") +} + +func (s *contractsSuite) verifyFabricatedBlockerIDRejected(managed *reportContract) { + bad := cloneReport(s.T(), managed) + bad.ManagedRecipe.BlockingGates = []string{gateG01, gateG04, "linux-arm64-kvm-001"} + s.Require().ErrorContains( + validateReportContract(bad), + "unknown gate \"linux-arm64-kvm-001\"", + ) + + raw, err := json.Marshal(bad) + s.Require().NoError(err) + s.Require().ErrorContains( + validateRawJSONAgainstSchema(raw, s.schema), + "linux-arm64-kvm-001", + ) +} + +func (s *contractsSuite) verifyLinuxARM64BlockedTuple(managed *reportContract) { + arm64Blocked := cloneReport(s.T(), managed) + arm64Blocked.Host.GOOS = osLinux + arm64Blocked.Host.GOARCH = archARM64 + arm64Blocked.Host.VirtualizationCapability = capKVMUnavailable + arm64Blocked.ManagedRecipe.RecipeID = "microsandbox-runtime-linux-arm64" + arm64Blocked.ManagedRecipe.Tuple = "linux/arm64" + arm64Blocked.ManagedRecipe.QualificationState = qualBlocked + arm64Blocked.ManagedRecipe.BlockingGates = []string{ + gateG01, + gateG02, + gateG04, + gateG06, + gateG07, + gateG09, + } + s.Require().NoError(validateReportContract(arm64Blocked)) +} + +func (s *contractsSuite) verifyDarwinARM64CandidateTuple(managed *reportContract) { + darwinCandidate := cloneReport(s.T(), managed) + darwinCandidate.Host.GOOS = osDarwin + darwinCandidate.Host.GOARCH = archARM64 + darwinCandidate.Host.VirtualizationCapability = capHypervisorFramework + darwinCandidate.ManagedRecipe.RecipeID = "microsandbox-runtime-darwin-arm64" + darwinCandidate.ManagedRecipe.Tuple = "darwin/arm64" + darwinCandidate.ManagedRecipe.BlockingGates = []string{ + gateG01, + gateG02, + gateG03, + gateG06, + gateG07, + gateG09, + } + s.Require().NoError(validateReportContract(darwinCandidate)) + + darwinWithLinuxGate := cloneReport(s.T(), darwinCandidate) + darwinWithLinuxGate.ManagedRecipe.BlockingGates = append( + slices.Clone(darwinWithLinuxGate.ManagedRecipe.BlockingGates), + gateG04, + ) + s.Require().ErrorContains( + validateReportContract(darwinWithLinuxGate), + "must not list Linux gate G04", + ) +} + +func (s *contractsSuite) assertFileIsASCIIOnly(path string) { + s.T().Helper() + raw, err := readTestFile(path) + s.Require().NoError(err) + for idx, b := range raw { + s.Require().Truef( + isAllowedASCIIByte(b), + "non-ASCII byte 0x%02x in %s at offset %d", + b, + path, + idx, + ) + } +} + +func (s *contractsSuite) verifyBaselineStatusEnvelope() { + var statusBuf bytes.Buffer + failedEvent := status.Event{ + Pipeline: status.PipelineProvider, + OperationID: "op-1", + ParentOperationID: "op-0", + Phase: status.PhaseRunningInit, + Step: "Check runtime", + State: status.StateFailed, + Duration: 42 * time.Millisecond, + Error: &status.ErrorInfo{ + Code: "provider_init_failed", + Message: "failed with super-secret-token", + Hint: "Verify runtime status", + Context: map[string]string{contextKeyProvider: providerMicroSandbox}, + }, + } + s.Require().NoError(devcconfig.WriteStatusJSON(&statusBuf, failedEvent)) + + line := strings.TrimSpace(statusBuf.String()) + parsed, ok := devcconfig.ParseStatusLine(line) + s.Require().True(ok) + s.Equal(status.PipelineProvider, parsed.Pipeline) + s.Equal("op-1", parsed.OperationID) + s.Equal("op-0", parsed.ParentOperationID) + s.Require().NotNil(parsed.Error) + s.Equal("failed with ***", parsed.Error.Message) + + var rawMap map[string]any + s.Require().NoError(json.Unmarshal([]byte(line), &rawMap)) + s.Equal("status", rawMap["kind"]) + s.Equal(float64(1), rawMap["schemaVersion"]) + s.NotContains(rawMap, "sequence") + s.NotContains(rawMap, "payload") + + _, ok = devcconfig.ParseStatusLine(strings.TrimSuffix(line, "}") + `,"sequence":1}`) + s.False(ok) + _, ok = devcconfig.ParseStatusLine(strings.TrimSuffix(line, "}") + `,"payload":{}}`) + s.False(ok) +} + +func (s *contractsSuite) verifyBaselineCLIErrorEnvelope() { + var errBuf bytes.Buffer + typedErr := &clierr.CLIError{ + Code: clierr.Code("provider_init_in_progress"), + Message: "provider init locked by super-secret-token", + Hint: "Wait for the active initialization to finish.", + Context: map[string]string{contextKeyProvider: providerMicroSandbox}, + } + s.Equal(75, exitcode.Retryable) + s.Require().NoError(devcconfig.WriteCLIErrorJSON(&errBuf, typedErr)) + + var errEnv devcconfig.ErrorEnvelope + s.Require().NoError(json.Unmarshal(errBuf.Bytes(), &errEnv)) + s.Equal("error", errEnv.Kind) + s.Equal("error", errEnv.Outcome) + s.Equal("provider_init_in_progress", errEnv.Code) + s.Equal("provider init locked by ***", errEnv.Message) + s.Equal("Wait for the active initialization to finish.", errEnv.Hint) + s.Equal(map[string]string{contextKeyProvider: providerMicroSandbox}, errEnv.Context) +} + +func (s *contractsSuite) verifyIndependentCanonicalReasonVocabulary() { + specSuccessReasons := []string{"dependency_ready"} + specSection63ErrorReasons := []string{ + "dependency_missing", + "dependency_incomplete", + "dependency_path_invalid", + "dependency_version_incompatible", + "dependency_version_unknown", + "dependency_platform_unsupported", + "dependency_policy_blocked", + "dependency_runtime_unreachable", + "dependency_auth_required", + "dependency_probe_timeout", + "dependency_integrity_failed", + "dependency_store_unwritable", + "dependency_recipe_unqualified", + "dependency_selection_stale", + "dependency_in_use", + "dependency_operation_interrupted", + } + addendumSection6ErrorReasons := []string{ + "dependency_configuration_conflict", + "dependency_offline_asset_missing", + "dependency_indirect_launcher", + } + s.Len(specSuccessReasons, 1) + s.Len(specSection63ErrorReasons, 16) + s.Len(addendumSection6ErrorReasons, 3) + + expected := slices.Concat( + specSuccessReasons, + specSection63ErrorReasons, + addendumSection6ErrorReasons, + ) + s.Len(expected, 20) + s.Equal(expected, s.schema.Defs["reasonCode"].Enum) + s.Equal(expected, toStrings(allReasonCodes)) + + guardMapRaw := string(s.readRawFixture("BASELINE_AND_GUARD_MAP.md")) + for _, code := range expected { + s.Contains(guardMapRaw, "`"+code+"`") + } +} + +func (s *contractsSuite) verifyRemovedReasonAliasesRejected() { + removedAliases := []string{ + "dependency_pair_incomplete", + "dependency_unsupported_platform", + "dependency_checksum_mismatch", + "dependency_archive_rejected", + "dependency_install_locked", + "dependency_install_cancelled", + "dependency_remove_refused_active", + "dependency_remove_refused_unowned", + "dependency_unknown_custom_source", + "dependency_virtualization_unavailable", + } + schemaEnum := s.schema.Defs["reasonCode"].Enum + goEnum := toStrings(allReasonCodes) + base := s.loadFixture(fixtureMissing) + + for _, alias := range removedAliases { + s.NotContains(schemaEnum, alias) + s.NotContains(goEnum, alias) + s.assertRemovedAliasRejectedAcrossPositions(base, reasonCode(alias)) + } +} + +func (s *contractsSuite) assertRemovedAliasRejectedAcrossPositions( + base *reportContract, + alias reasonCode, +) { + s.T().Helper() + mutators := []func(*reportContract){ + func(r *reportContract) { r.ReasonCode = alias }, + func(r *reportContract) { r.Items[0].ReasonCode = alias }, + func(r *reportContract) { r.Items[0].Candidates[0].ReasonCode = alias }, + func(r *reportContract) { + r.Actions[0].Enabled = false + r.Actions[0].DisabledReasonCode = alias + }, + } + for _, mutate := range mutators { + m := cloneReport(s.T(), base) + mutate(m) + s.Require().Error(validateReportContract(m)) + raw, err := json.Marshal(m) + s.Require().NoError(err) + s.Require().ErrorContains(validateRawJSONAgainstSchema(raw, s.schema), string(alias)) + } +} + +func (s *contractsSuite) verifyCanonicalReasonDimensionSemantics() { + s.verifyValidCanonicalReasonScenarios() + s.verifyInvalidCanonicalReasonDimensionCollapse() +} + +func (s *contractsSuite) verifyValidCanonicalReasonScenarios() { + missing := s.loadFixture(fixtureMissing) + pathInvalid := cloneReport(s.T(), missing) + pathInvalid.ReasonCode = reasonPathInvalid + pathInvalid.Items[0].ReasonCode = reasonPathInvalid + pathInvalid.Items[0].Candidates[0].ReasonCode = reasonPathInvalid + s.assertValidMutatedReport(pathInvalid) + + external := s.loadFixture(fixtureExternal) + verIncompat := cloneReport(s.T(), external) + verIncompat.Compatibility = compatibilityIncompatible + verIncompat.Reachability = reachabilityNotChecked + verIncompat.ReasonCode = reasonVersionIncompatible + verIncompat.Items[0].Compatibility = compatibilityIncompatible + verIncompat.Items[0].Reachability = reachabilityNotChecked + verIncompat.Items[0].ReasonCode = reasonVersionIncompatible + verIncompat.Items[0].Candidates[0].Compatibility = compatibilityIncompatible + verIncompat.Items[0].Candidates[0].ReasonCode = reasonVersionIncompatible + s.assertValidMutatedReport(verIncompat) + + s.verifyValidAuthRequiredScenarios(external) + s.verifyValidActiveAndActionReasonScenarios() +} + +func (s *contractsSuite) verifyValidAuthRequiredScenarios(external *reportContract) { + passiveAuth := buildPassiveAuthRequiredReport(s.T(), external) + s.assertValidMutatedReport(passiveAuth) + + preExecBlocked := cloneReport(s.T(), passiveAuth) + preExecBlocked.SurveyMode = surveyModeActiveProbe + s.assertValidMutatedReport(preExecBlocked) + + activeNotChecked := cloneReport(s.T(), external) + activeNotChecked.Reachability = reachabilityNotChecked + activeNotChecked.ReasonCode = reasonAuthRequired + activeNotChecked.Items[0].Reachability = reachabilityNotChecked + activeNotChecked.Items[0].ReasonCode = reasonAuthRequired + s.assertValidMutatedReport(activeNotChecked) +} + +func (s *contractsSuite) verifyValidActiveAndActionReasonScenarios() { + stopped := s.loadFixture(fixtureStoppedRuntime) + authReq := cloneReport(s.T(), stopped) + authReq.ReasonCode = reasonAuthRequired + authReq.Items[0].ReasonCode = reasonAuthRequired + s.assertValidMutatedReport(authReq) + + probeTimeout := cloneReport(s.T(), stopped) + probeTimeout.Compatibility = compatibilityUnknown + probeTimeout.Reachability = reachabilityUnreachable + probeTimeout.ReasonCode = reasonProbeTimeout + probeTimeout.Items[0].Compatibility = compatibilityUnknown + probeTimeout.Items[0].Reachability = reachabilityUnreachable + probeTimeout.Items[0].ReasonCode = reasonProbeTimeout + s.assertValidMutatedReport(probeTimeout) + + incomplete := s.loadFixture(fixtureIncompletePair) + for _, actionReason := range []reasonCode{ + reasonIntegrityFailed, + reasonStoreUnwritable, + reasonInUse, + reasonOperationInterrupted, + reasonPolicyBlocked, + } { + m := cloneReport(s.T(), incomplete) + m.Actions[0].Enabled = false + m.Actions[0].DisabledReasonCode = actionReason + s.assertValidMutatedReport(m) + } +} + +func (s *contractsSuite) verifyInvalidCanonicalReasonDimensionCollapse() { + external := s.loadFixture(fixtureExternal) + + badVerIncompat := cloneReport(s.T(), external) + badVerIncompat.ReasonCode = reasonVersionIncompatible + s.Require().ErrorContains( + validateReportContract(badVerIncompat), + `requires availability="available" and compatibility="incompatible"`, + ) + + badVerUnknown := cloneReport(s.T(), external) + badVerUnknown.ReasonCode = reasonVersionUnknown + s.Require().ErrorContains( + validateReportContract(badVerUnknown), + `requires availability="available" and compatibility="unknown"`, + ) + + badIncomplete := cloneReport(s.T(), external) + badIncomplete.ReasonCode = reasonIncomplete + s.Require().ErrorContains( + validateReportContract(badIncomplete), + `requires availability="incomplete"`, + ) + + badPlatform := cloneReport(s.T(), external) + badPlatform.ReasonCode = reasonPlatformUnsupported + s.Require().ErrorContains( + validateReportContract(badPlatform), + `requires policy="unsupported"`, + ) + + badPathInvalid := cloneReport(s.T(), external) + badPathInvalid.ReasonCode = reasonPathInvalid + s.Require().ErrorContains( + validateReportContract(badPathInvalid), + `cannot report availability="available"`, + ) + + missing := s.loadFixture(fixtureMissing) + s.verifyInvalidAuthRequiredScenarios(external, missing) + + badTimeout := cloneReport(s.T(), missing) + badTimeout.ReasonCode = reasonProbeTimeout + s.Require().ErrorContains(validateReportContract(badTimeout), "requires active_probe") +} + +func (s *contractsSuite) verifyInvalidAuthRequiredScenarios( + external, missing *reportContract, +) { + badMissingAuth := cloneReport(s.T(), missing) + badMissingAuth.ReasonCode = reasonAuthRequired + s.Require().ErrorContains( + validateReportContract(badMissingAuth), + `requires availability="available"`, + ) + + passiveAuth := buildPassiveAuthRequiredReport(s.T(), external) + + passiveExecuted := cloneReport(s.T(), passiveAuth) + passiveExecuted.Executed = true + s.Require().ErrorContains( + validateReportContract(passiveExecuted), + "passive survey must have executed=false", + ) + + passiveUnreachable := cloneReport(s.T(), passiveAuth) + passiveUnreachable.Reachability = reachabilityUnreachable + s.Require().ErrorContains( + validateReportContract(passiveUnreachable), + `passive survey must not report reachability="unreachable"`, + ) + + unexecCompat := cloneReport(s.T(), passiveAuth) + unexecCompat.SurveyMode = surveyModeActiveProbe + unexecCompat.Compatibility = compatibilityCompatible + s.Require().ErrorContains( + validateReportContract(unexecCompat), + `unexecuted reasonCode="dependency_auth_required" requires compatibility="unknown" and reachability="not_checked"`, + ) + + reachableAuth := cloneReport(s.T(), external) + reachableAuth.ReasonCode = reasonAuthRequired + s.Require().ErrorContains( + validateReportContract(reachableAuth), + `cannot report reachability="reachable"`, + ) +} + +func (s *contractsSuite) assertValidMutatedReport(r *reportContract) { + s.T().Helper() + raw, err := json.Marshal(r) + s.Require().NoError(err) + _, err = s.decodeAndValidateRaw(raw) + s.Require().NoError(err) +} + +func (s *contractsSuite) verifyAvailableAndMissingCandidateObservations() { + fixtures := []string{ + fixtureMissing, + fixtureExternal, + fixtureIncompletePair, + fixtureManagedDisabled, + fixtureUnsupportedHost, + fixtureStoppedRuntime, + fixtureStaleTarget, + fixtureUnknownCustom, + fixtureConfigConflict, + fixtureOfflineMissing, + } + availableCount := 0 + missingCount := 0 + for _, filename := range fixtures { + avail, miss := s.verifyFixtureCandidateObservations(filename) + availableCount += avail + missingCount += miss + } + s.Positive(availableCount) + s.Positive(missingCount) +} + +func (s *contractsSuite) verifyFixtureCandidateObservations(filename string) (int, int) { + s.T().Helper() + report := s.loadFixture(filename) + avail := 0 + miss := 0 + for _, item := range report.Items { + for _, cand := range item.Candidates { + a, m := s.verifySingleCandidateObservation(filename, &report.Target, &cand) + avail += a + miss += m + } + } + return avail, miss +} + +func (s *contractsSuite) verifySingleCandidateObservation( + filename string, + target *targetIdentity, + cand *candidateObservation, +) (int, int) { + s.T().Helper() + if cand.Availability == availabilityAvailable { + s.Require().NotNil(cand.Observation, "fixture %s candidate %s", filename, cand.LexicalPath) + s.NotEmpty(cand.Observation.FileIdentity) + s.NotEqual(cand.LexicalPath, cand.Observation.FileIdentity) + s.NotEqual(cand.ResolvedPath, cand.Observation.FileIdentity) + s.NotEqual(target.ConfigRevision, cand.Observation.FileIdentity) + s.NotEqual(target.ProviderConfigRevision, cand.Observation.FileIdentity) + return 1, 0 + } + if cand.Availability == availabilityMissing { + s.Nil(cand.Observation, "fixture %s missing candidate %s", filename, cand.LexicalPath) + return 0, 1 + } + return 0, 0 +} + +func (s *contractsSuite) verifyCandidateObservationMutationsRejected() { + external := s.loadFixture(fixtureExternal) + + missingObs := cloneReport(s.T(), external) + missingObs.Items[0].Candidates[0].Observation = nil + s.Require().ErrorContains( + validateReportContract(missingObs), + "must record non-empty observation.fileIdentity", + ) + + pathIdentity := cloneReport(s.T(), external) + pathIdentity.Items[0].Candidates[0].Observation.FileIdentity = pathIdentity.Items[0].Candidates[0].ResolvedPath + s.Require().ErrorContains( + validateReportContract(pathIdentity), + "distinct from lexicalPath and resolvedPath", + ) + + revIdentity := cloneReport(s.T(), external) + revIdentity.Items[0].Candidates[0].Observation.FileIdentity = revIdentity.Target.ProviderConfigRevision + s.Require().ErrorContains( + validateReportContract(revIdentity), + "distinct from target config/provider revisions", + ) + + missing := s.loadFixture(fixtureMissing) + fabricatedMissing := cloneReport(s.T(), missing) + fabricatedMissing.Items[0].Candidates[0].Observation = &candidateFileObservation{ + FileIdentity: "obs-file:linux-amd64:fabricated-01", + } + s.Require().ErrorContains( + validateReportContract(fabricatedMissing), + "must not fabricate an observation record", + ) + + incomplete := s.loadFixture(fixtureIncompletePair) + passiveVersion := cloneReport(s.T(), incomplete) + passiveVersion.Items[0].Candidates[1].Observation.ObservedVersion = "0.7.7" + s.Require().ErrorContains( + validateReportContract(passiveVersion), + "must not claim observation.observedVersion", + ) + + externalRaw := s.readRawFixture(fixtureExternal) + s.runRawShapeCase(rawShapeCase{ + name: "available candidate observation missing fileIdentity rejected by schema", + base: externalRaw, + mutate: func(doc map[string]any) { + obs := firstCandidateMap(doc)["observation"].(map[string]any) + delete(obs, "fileIdentity") + }, + errSub: `$.items[0].candidates[0].observation: missing required field "fileIdentity"`, + }) +} + +func (s *contractsSuite) verifySymlinkTargetUpdatePreservesLexicalPathWithDistinctIdentity() { + before := s.loadFixture(fixtureExternal) + beforeCand := before.Items[0].Candidates[0] + + after := cloneReport(s.T(), before) + after.SurveyMode = surveyModePassive + after.Executed = false + after.Compatibility = compatibilityUnknown + after.Reachability = reachabilityNotChecked + after.ReasonCode = reasonVersionUnknown + after.Items[0].Executed = false + after.Items[0].Compatibility = compatibilityUnknown + after.Items[0].Reachability = reachabilityNotChecked + after.Items[0].ReasonCode = reasonVersionUnknown + + afterCand := &after.Items[0].Candidates[0] + afterCand.Executed = false + afterCand.Compatibility = compatibilityUnknown + afterCand.ReasonCode = reasonVersionUnknown + afterCand.ResolvedPath = "/opt/homebrew/Cellar/docker/28.0.2/bin/docker" + afterCand.Observation = &candidateFileObservation{ + FileIdentity: "illustrative-fid:darwin-arm64:docker-28.0.2-cellar-a41c", + Platform: "darwin/arm64", + } + + s.Equal(beforeCand.LexicalPath, afterCand.LexicalPath) + s.True(afterCand.IsSymlink) + s.NotEqual(beforeCand.Observation.FileIdentity, afterCand.Observation.FileIdentity) + s.assertValidMutatedReport(after) + + prematureCompat := cloneReport(s.T(), after) + prematureCompat.Compatibility = compatibilityCompatible + s.Require().ErrorContains( + validateReportContract(prematureCompat), + "must not claim verified compatibility", + ) +} + +func (s *contractsSuite) verifyUnexecutedCandidateCompatibleRejected(conflict *reportContract) { + passiveCandidateCompat := cloneReport(s.T(), conflict) + passiveCandidateCompat.Items[0].Candidates[1].Compatibility = compatibilityCompatible + s.Require().ErrorContains( + validateReportContract(passiveCandidateCompat), + "unexecuted candidate \"/usr/bin/docker\" (executed=false) must not claim verified compatibility=\"compatible\"", + ) + rawPassive, err := json.Marshal(passiveCandidateCompat) + s.Require().NoError(err) + _, err = s.decodeAndValidateRaw(rawPassive) + s.Require().ErrorContains( + err, + "unexecuted candidate \"/usr/bin/docker\" (executed=false) must not claim verified compatibility=\"compatible\"", + ) + + activeWithUnprobed := s.buildActiveReportWithUnprobedSecondaryCandidate() + s.assertValidMutatedReport(activeWithUnprobed) + + activeUnprobedCompat := cloneReport(s.T(), activeWithUnprobed) + activeUnprobedCompat.Items[0].Candidates[1].Compatibility = compatibilityCompatible + s.Require().ErrorContains( + validateReportContract(activeUnprobedCompat), + "unexecuted candidate \"/usr/local/bin/docker\" (executed=false) "+ + "must not claim verified compatibility=\"compatible\"", + ) +} + +func (s *contractsSuite) buildActiveReportWithUnprobedSecondaryCandidate() *reportContract { + active := s.loadFixture(fixtureExternal) + active.Items[0].Candidates = append(active.Items[0].Candidates, candidateObservation{ + Component: "docker", + SourceKind: candidateSourceWellKnownPath, + OptionName: "DOCKER_PATH", + LexicalPath: "/usr/local/bin/docker", + ResolvedPath: "/usr/local/bin/docker", + Observation: &candidateFileObservation{ + FileIdentity: "illustrative-fid:darwin-arm64:usr-local-docker-77b1", + Platform: active.Items[0].Candidates[0].Observation.Platform, + }, + Executed: false, + Selected: false, + Availability: availabilityAvailable, + Compatibility: compatibilityUnknown, + ReasonCode: reasonVersionUnknown, + Detail: "Unprobed secondary candidate on well-known path.", + }) + return active +} + +func (s *contractsSuite) verifyUnsupportedSchemaKeywordsRejected() { + schemaRaw := s.readRawFixture("schema.json") + _, err := parseSchemaBytes(schemaRaw) + s.Require().NoError(err) + s.verifyRefWithMetadataOnlySiblingAccepted(schemaRaw) + s.verifyZeroLimitsAccepted(schemaRaw) + + cases := slices.Concat( + buildUnsupportedSchemaKeywordCases(), + buildIgnoredSchemaKeywordCombinationCases(), + buildInvalidSchemaConstraintValueCases(), + ) + for _, tc := range cases { + s.Run(tc.name, func() { + var doc map[string]any + s.Require().NoError(json.Unmarshal(schemaRaw, &doc)) + tc.mutate(doc) + mutated, err := json.Marshal(doc) + s.Require().NoError(err) + _, err = parseSchemaBytes(mutated) + s.Require().ErrorContains(err, tc.errSub) + }) + } +} + +func (s *contractsSuite) verifyRefWithMetadataOnlySiblingAccepted(schemaRaw []byte) { + var doc map[string]any + s.Require().NoError(json.Unmarshal(schemaRaw, &doc)) + avail := schemaRootPropertyMap(doc, "availability") + avail["title"] = "AvailabilityDim" + avail["description"] = "Documented $ref without validation siblings." + mutated, err := json.Marshal(doc) + s.Require().NoError(err) + + parsed, err := parseSchemaBytes(mutated) + s.Require().NoError(err) + s.Require().NoError(validateRawJSONAgainstSchema(s.readRawFixture(fixtureMissing), parsed)) +} + +func (s *contractsSuite) verifyZeroLimitsAccepted(schemaRaw []byte) { + var doc map[string]any + s.Require().NoError(json.Unmarshal(schemaRaw, &doc)) + schemaRootPropertyMap(doc, "message")["minLength"] = 0 + schemaRootPropertyMap(doc, "items")["minItems"] = 0 + relaxedRaw, err := json.Marshal(doc) + s.Require().NoError(err) + relaxed, err := parseSchemaBytes(relaxedRaw) + s.Require().NoError(err) + + var report map[string]any + s.Require().NoError(json.Unmarshal(s.readRawFixture(fixtureMissing), &report)) + report["message"] = "" + report["items"] = []any{} + reportRaw, err := json.Marshal(report) + s.Require().NoError(err) + + s.Require().NoError(validateRawJSONAgainstSchema(reportRaw, relaxed)) + baseline, err := parseSchemaBytes(schemaRaw) + s.Require().NoError(err) + s.Require().Error(validateRawJSONAgainstSchema(reportRaw, baseline)) +} + +func readTestFile(relPath string) ([]byte, error) { + clean := filepath.ToSlash(filepath.Clean(relPath)) + return fs.ReadFile(os.DirFS("."), clean) +} + +func isAllowedASCIIByte(b byte) bool { + if b == '\n' || b == '\r' || b == '\t' { + return true + } + return b >= 0x20 && b <= 0x7e +} + +func loadSchemaDoc(path string) (*jsonSchemaNode, error) { + raw, err := readTestFile(path) + if err != nil { + return nil, err + } + return parseSchemaBytes(raw) +} + +func parseSchemaBytes(raw []byte) (*jsonSchemaNode, error) { + rawDec := json.NewDecoder(bytes.NewReader(raw)) + rawDec.UseNumber() + var rawDoc any + if err := rawDec.Decode(&rawDoc); err != nil { + return nil, err + } + if err := validateSchemaNodeKeywords(rawDoc, "$"); err != nil { + return nil, err + } + dec := json.NewDecoder(bytes.NewReader(raw)) + dec.UseNumber() + dec.DisallowUnknownFields() + var root jsonSchemaNode + if err := dec.Decode(&root); err != nil { + return nil, err + } + var extra any + if err := dec.Decode(&extra); err != io.EOF { + return nil, fmt.Errorf("unexpected trailing JSON content in schema") + } + return &root, nil +} + +func validateSchemaNodeKeywords(raw any, path string) error { + nodeMap, ok := raw.(map[string]any) + if !ok { + return fmt.Errorf("%s: schema node must be an object, got %T", path, raw) + } + keys := slices.Sorted(maps.Keys(nodeMap)) + for _, k := range keys { + if !slices.Contains(allowedSchemaNodeKeywords, k) { + return fmt.Errorf("%s: unsupported schema keyword %q", path, k) + } + } + if err := validateSchemaKeywordContext(nodeMap, keys, path); err != nil { + return err + } + for _, k := range keys { + if err := validateSchemaChildKeyword(k, nodeMap[k], path); err != nil { + return err + } + } + return nil +} + +// validateSchemaKeywordContext rejects keyword/type combinations that +// validateSchemaValue would otherwise skip without evaluating them. +func validateSchemaKeywordContext(nodeMap map[string]any, keys []string, path string) error { + if _, isRef := nodeMap[keywordRef]; isRef { + return validateSchemaRefNode(keys, path) + } + typeName, _ := nodeMap[keywordType].(string) + supported, known := schemaKeywordsByType[typeName] + if !known { + return fmt.Errorf( + "%s: schema node requires type object, array, string, integer or boolean, got %v", + path, + nodeMap[keywordType], + ) + } + if err := validateSchemaTypedKeywords(keys, supported, typeName, path); err != nil { + return err + } + return validateSchemaConstraintValues(nodeMap, typeName, path) +} + +func validateSchemaTypedKeywords(keys, supported []string, typeName, path string) error { + for _, k := range keys { + if slices.Contains(schemaMetadataKeywords, k) || k == keywordType { + continue + } + if k == keywordDefs && path == "$" { + continue + } + if !slices.Contains(supported, k) { + return fmt.Errorf( + "%s: keyword %q is not supported on schema type %q", + path, + k, + typeName, + ) + } + } + return nil +} + +func validateSchemaRefNode(keys []string, path string) error { + for _, k := range keys { + if k != keywordRef && !slices.Contains(schemaMetadataKeywords, k) { + return fmt.Errorf("%s: $ref node cannot combine with validation keyword %q", path, k) + } + } + return nil +} + +func validateSchemaConstraintValues(nodeMap map[string]any, typeName, path string) error { + if err := validateSchemaConst(nodeMap, typeName, path); err != nil { + return err + } + if enum, ok := nodeMap[keywordEnum]; ok { + if err := validateSchemaEnum(enum, path+"."+keywordEnum); err != nil { + return err + } + } + for _, keyword := range []string{keywordMinLength, keywordMinItems} { + if limit, ok := nodeMap[keyword]; ok { + if err := validateSchemaLimit(limit, path+"."+keyword); err != nil { + return err + } + } + } + return nil +} + +func validateSchemaConst(nodeMap map[string]any, typeName, path string) error { + val, ok := nodeMap[keywordConst] + if !ok { + return nil + } + switch typeName { + case schemaTypeString: + if _, isString := val.(string); !isString { + return fmt.Errorf("%s.const: expected string const for type %q", path, typeName) + } + case schemaTypeInteger: + if _, isInteger := schemaIntegerToken(val); !isInteger { + return fmt.Errorf("%s.const: expected integer const for type %q", path, typeName) + } + } + return nil +} + +func validateSchemaEnum(val any, path string) error { + values, ok := val.([]any) + if !ok || len(values) == 0 { + return fmt.Errorf("%s: expected non-empty string array", path) + } + for _, v := range values { + if _, isString := v.(string); !isString { + return fmt.Errorf("%s: expected non-empty string array", path) + } + } + return nil +} + +// validateSchemaLimit accepts zero: minLength and minItems of 0 are valid +// no-op limits that the evaluator handles correctly. +func validateSchemaLimit(val any, path string) error { + limit, isInteger := schemaIntegerToken(val) + if !isInteger || limit < 0 { + return fmt.Errorf("%s: expected non-negative integer", path) + } + return nil +} + +// schemaIntegerToken accepts only plain JSON integer tokens within int64. +// Fraction or exponent forms are rejected rather than rounded so a schema +// constraint can never silently differ from its written value. +func schemaIntegerToken(val any) (int64, bool) { + num, ok := val.(json.Number) + if !ok { + return 0, false + } + parsed, err := num.Int64() + return parsed, err == nil +} + +func validateSchemaChildKeyword(key string, val any, path string) error { + switch key { + case keywordDefs, keywordProperties: + subMap, ok := val.(map[string]any) + if !ok { + return fmt.Errorf("%s.%s: expected object map, got %T", path, key, val) + } + for subKey, subVal := range subMap { + if err := validateSchemaNodeKeywords(subVal, path+"."+key+"."+subKey); err != nil { + return err + } + } + case keywordItems: + return validateSchemaNodeKeywords(val, path+"."+keywordItems) + } + return nil +} + +func validateRawJSONAgainstSchema(raw []byte, rootSchema *jsonSchemaNode) error { + dec := json.NewDecoder(bytes.NewReader(raw)) + dec.UseNumber() + + var doc any + if err := dec.Decode(&doc); err != nil { + return fmt.Errorf("decode JSON: %w", err) + } + var extra any + if err := dec.Decode(&extra); err != io.EOF { + return fmt.Errorf("unexpected trailing JSON content after root document") + } + + return validateSchemaValue(rootSchema, rootSchema, "$", doc) +} + +func validateSchemaValue(root, node *jsonSchemaNode, path string, val any) error { + if node.Ref != "" { + return validateSchemaRef(root, node.Ref, path, val) + } + switch node.Type { + case schemaTypeObject: + return validateSchemaObject(root, node, path, val) + case schemaTypeArray: + return validateSchemaArray(root, node, path, val) + case schemaTypeString: + return validateSchemaString(node, path, val) + case schemaTypeInteger: + return validateSchemaInteger(node, path, val) + case schemaTypeBoolean: + return validateSchemaBoolean(path, val) + default: + return fmt.Errorf("%s: unsupported schema type %q", path, node.Type) + } +} + +func validateSchemaRef(root *jsonSchemaNode, ref, path string, val any) error { + const defPrefix = "#/$defs/" + if !strings.HasPrefix(ref, defPrefix) { + return fmt.Errorf("%s: unsupported schema $ref %q", path, ref) + } + defName := strings.TrimPrefix(ref, defPrefix) + target, ok := root.Defs[defName] + if !ok { + return fmt.Errorf("%s: unknown schema $ref %q", path, ref) + } + return validateSchemaValue(root, &target, path, val) +} + +func validateSchemaObject(root, node *jsonSchemaNode, path string, val any) error { + obj, ok := val.(map[string]any) + if !ok { + return fmt.Errorf("%s: expected object, got %T", path, val) + } + if err := checkRequiredAndUnknownFields(node, path, obj); err != nil { + return err + } + for k, v := range obj { + propSchema, declared := node.Properties[k] + if !declared { + continue + } + if err := validateSchemaValue(root, &propSchema, path+"."+k, v); err != nil { + return err + } + } + return nil +} + +func checkRequiredAndUnknownFields( + node *jsonSchemaNode, + path string, + obj map[string]any, +) error { + for _, req := range node.Required { + if _, exists := obj[req]; !exists { + return fmt.Errorf("%s: missing required field %q", path, req) + } + } + if node.AdditionalProperties == nil || *node.AdditionalProperties { + return nil + } + for k := range obj { + if _, declared := node.Properties[k]; !declared { + return fmt.Errorf("%s: unknown field %q", path, k) + } + } + return nil +} + +func validateSchemaArray(root, node *jsonSchemaNode, path string, val any) error { + arr, ok := val.([]any) + if !ok { + return fmt.Errorf("%s: expected array, got %T", path, val) + } + if len(arr) < node.MinItems { + return fmt.Errorf("%s: array length %d is below minItems %d", path, len(arr), node.MinItems) + } + if node.Items == nil { + return nil + } + for i, elem := range arr { + elemPath := fmt.Sprintf("%s[%d]", path, i) + if err := validateSchemaValue(root, node.Items, elemPath, elem); err != nil { + return err + } + } + return nil +} + +func validateSchemaString(node *jsonSchemaNode, path string, val any) error { + s, ok := val.(string) + if !ok { + return fmt.Errorf("%s: expected string, got %T", path, val) + } + if length := utf8.RuneCountInString(s); length < node.MinLength { + return fmt.Errorf( + "%s: string length %d is below minLength %d", + path, + length, + node.MinLength, + ) + } + if constStr, ok := node.Const.(string); ok && s != constStr { + return fmt.Errorf("%s: expected const %q, got %q", path, constStr, s) + } + if len(node.Enum) > 0 && !slices.Contains(node.Enum, s) { + return fmt.Errorf("%s: value %q is not in enum %v", path, s, node.Enum) + } + return nil +} + +func validateSchemaInteger(node *jsonSchemaNode, path string, val any) error { + num, ok := val.(json.Number) + if !ok || strings.ContainsAny(num.String(), ".eE") { + return fmt.Errorf("%s: expected integer, got %v (%T)", path, val, val) + } + parsedInt, err := num.Int64() + if err != nil { + return fmt.Errorf("%s: invalid integer %s: %w", path, num.String(), err) + } + if node.Const == nil { + return nil + } + constInt, ok := schemaIntegerToken(node.Const) + if !ok { + return fmt.Errorf("%s: unsupported integer const %v", path, node.Const) + } + if parsedInt != constInt { + return fmt.Errorf("%s: expected const %d, got %d", path, constInt, parsedInt) + } + return nil +} + +func validateSchemaBoolean(path string, val any) error { + if _, ok := val.(bool); !ok { + return fmt.Errorf("%s: expected boolean, got %T", path, val) + } + return nil +} + +func validateReportContract(r *reportContract) error { + if err := validateReportHeader(r); err != nil { + return err + } + ctx, err := buildTargetContext(r) + if err != nil { + return err + } + if err := validateHostIdentity(&r.Host); err != nil { + return err + } + if err := validateDimensions(ctx, reportDimensions(r)); err != nil { + return err + } + if err := validateManagedRecipe(ctx); err != nil { + return err + } + return validateReportItemsAndActions(ctx) +} + +func validateReportHeader(r *reportContract) error { + if r == nil { + return fmt.Errorf("report is nil") + } + if r.Schema != reportSchemaID { + return fmt.Errorf("unexpected schema %q", r.Schema) + } + if r.SchemaVersion != reportSchemaVersion { + return fmt.Errorf("unexpected schemaVersion %d", r.SchemaVersion) + } + if !slices.Contains(allSurveyModes, r.SurveyMode) { + return fmt.Errorf("invalid surveyMode %q", r.SurveyMode) + } + if strings.TrimSpace(r.Message) == "" { + return fmt.Errorf("message is required") + } + return nil +} + +func reportDimensions(r *reportContract) dimensionSet { + return dimensionSet{ + mode: r.SurveyMode, + executed: r.Executed, + avail: r.Availability, + compat: r.Compatibility, + reach: r.Reachability, + policy: r.Policy, + reason: r.ReasonCode, + } +} + +func itemDimensions(r *reportContract, item *dependencyItemReport) dimensionSet { + return dimensionSet{ + mode: r.SurveyMode, + executed: item.Executed, + avail: item.Availability, + compat: item.Compatibility, + reach: item.Reachability, + policy: item.Policy, + reason: item.ReasonCode, + } +} + +func validateReportItemsAndActions(ctx targetContext) error { + r := ctx.report + if len(r.Items) == 0 { + return fmt.Errorf("items must not be empty") + } + for i := range r.Items { + if err := validateItem(ctx, &r.Items[i]); err != nil { + return fmt.Errorf("items[%d]: %w", i, err) + } + } + for i := range r.Actions { + if err := validateAction(ctx, &r.Actions[i]); err != nil { + return fmt.Errorf("actions[%d]: %w", i, err) + } + } + return nil +} + +func buildTargetContext(r *reportContract) (targetContext, error) { + if err := validateRequiredTargetFields(&r.Target); err != nil { + return targetContext{}, err + } + ctx, err := classifyTargetSource(r) + if err != nil { + return targetContext{}, err + } + if err := validateTargetStaleness(r); err != nil { + return targetContext{}, err + } + return ctx, nil +} + +func validateRequiredTargetFields(t *targetIdentity) error { + required := []struct { + field string + val string + }{ + {"target.contextName", t.ContextName}, + {"target.providerName", t.ProviderName}, + {"target.providerType", t.ProviderType}, + {"target.providerSourceId", t.ProviderSourceID}, + {"target.configRevision", t.ConfigRevision}, + {"target.providerConfigRevision", t.ProviderConfigRevision}, + {"target.evaluatedAt", t.EvaluatedAt}, + } + for _, item := range required { + if strings.TrimSpace(item.val) == "" { + return fmt.Errorf("%s is required", item.field) + } + } + if !slices.Contains(allProviderSourceKinds, t.ProviderSourceKind) { + return fmt.Errorf("invalid target.providerSourceKind %q", t.ProviderSourceKind) + } + return nil +} + +func classifyTargetSource(r *reportContract) (targetContext, error) { + switch r.Target.ProviderSourceKind { + case providerSourceBuiltinInternal: + return validateBuiltinInternalTarget(r) + case providerSourceCanonicalExternalRelease: + return validateCanonicalExternalTarget(r) + case providerSourceCustomGitHub, providerSourceCustomLocal, providerSourceCustomURL: + return validateCustomTarget(r) + default: + return targetContext{}, fmt.Errorf( + "unsupported source kind %q", + r.Target.ProviderSourceKind, + ) + } +} + +func validateBuiltinInternalTarget(r *reportContract) (targetContext, error) { + t := &r.Target + if !slices.Contains(builtinInternalProviderTypes, t.ProviderType) { + return targetContext{}, fmt.Errorf( + "builtin_internal target.providerType %q must be one of %v", + t.ProviderType, + builtinInternalProviderTypes, + ) + } + expectedSourceID := "internal:" + t.ProviderType + if t.ProviderSourceID != expectedSourceID { + return targetContext{}, fmt.Errorf( + "builtin_internal source must equal %q for providerType %q, got %q", + expectedSourceID, + t.ProviderType, + t.ProviderSourceID, + ) + } + if t.AdapterVersion != "" { + return targetContext{}, fmt.Errorf( + "builtin_internal source must not set adapterVersion, got %q", + t.AdapterVersion, + ) + } + if !t.TrustedBuiltinIdentity { + return targetContext{}, fmt.Errorf( + "builtin_internal source must have trustedBuiltinIdentity=true", + ) + } + return targetContext{report: r}, nil +} + +func validateCanonicalExternalTarget(r *reportContract) (targetContext, error) { + t := &r.Target + spec, err := parseCanonicalExternalSource(t.ProviderSourceID) + if err != nil { + return targetContext{}, err + } + baseline := canonicalExternalAdapters[spec.repo] + if spec.ver.GT(baseline.maxPublishedVersion) { + return targetContext{}, fmt.Errorf( + "canonical source %q references unreleased synthetic version %q (latest published is v%s)", + t.ProviderSourceID, + spec.tag, + baseline.maxPublishedVersion.String(), + ) + } + if t.ProviderType != providerTypeExternal { + return targetContext{}, fmt.Errorf( + "canonical_external_release must have providerType=%q, got %q", + providerTypeExternal, + t.ProviderType, + ) + } + if t.AdapterVersion != spec.tag { + return targetContext{}, fmt.Errorf( + "canonical_external_release adapterVersion %q must match source tag %q", + t.AdapterVersion, + spec.tag, + ) + } + if !t.TrustedBuiltinIdentity { + return targetContext{}, fmt.Errorf( + "canonical_external_release source must have trustedBuiltinIdentity=true", + ) + } + return targetContext{ + report: r, + isCanonicalMSB: spec.repo == canonicalMicroSandboxRepo, + adapterSupportsT08: baseline.supportsPathPairRuntimeCheck, + }, nil +} + +func parseCanonicalExternalSource(sourceID string) (canonicalSourceSpec, error) { + parts := strings.Split(sourceID, "@") + if len(parts) != 2 { + return canonicalSourceSpec{}, fmt.Errorf( + "canonical_external_release source %q must have exact @ format", + sourceID, + ) + } + repo, tag := parts[0], parts[1] + if _, ok := canonicalExternalAdapters[repo]; !ok { + return canonicalSourceSpec{}, fmt.Errorf( + "canonical_external_release repository %q is not an approved canonical devsy-org adapter", + repo, + ) + } + ver, err := parsePinnedReleaseSemver(tag) + if err != nil { + return canonicalSourceSpec{}, err + } + return canonicalSourceSpec{repo: repo, tag: tag, ver: ver}, nil +} + +func parsePinnedReleaseSemver(tag string) (semver.Version, error) { + if !strings.HasPrefix(tag, "v") { + return semver.Version{}, fmt.Errorf( + "canonical_external_release tag %q must have v-prefixed pinned semver", + tag, + ) + } + ver, err := semver.Parse(strings.TrimPrefix(tag, "v")) + if err != nil || !isCleanReleaseVersion(ver, tag) { + return semver.Version{}, fmt.Errorf( + "canonical_external_release tag %q is not a valid pinned release semver", + tag, + ) + } + return ver, nil +} + +func isCleanReleaseVersion(ver semver.Version, tag string) bool { + if len(ver.Pre) > 0 || len(ver.Build) > 0 { + return false + } + return "v"+ver.String() == tag +} + +func validateCustomTarget(r *reportContract) (targetContext, error) { + if r.Target.TrustedBuiltinIdentity { + return targetContext{}, fmt.Errorf( + "custom provider source %q must not set trustedBuiltinIdentity=true", + r.Target.ProviderSourceID, + ) + } + if r.Policy != policyUnmanagedCustomSource { + return targetContext{}, fmt.Errorf( + "custom provider source must use policy=%q, got %q", + policyUnmanagedCustomSource, + r.Policy, + ) + } + if r.ReasonCode != reasonPolicyBlocked { + return targetContext{}, fmt.Errorf( + "custom provider source must use reasonCode=%q, got %q", + reasonPolicyBlocked, + r.ReasonCode, + ) + } + if r.ManagedRecipe != nil { + return targetContext{}, fmt.Errorf("custom provider source must not attach a managedRecipe") + } + return targetContext{report: r}, nil +} + +func validateTargetStaleness(r *reportContract) error { + t := &r.Target + if t.StaleAgainstRevision == "" || t.StaleAgainstRevision == t.ProviderConfigRevision { + return nil + } + if r.ReasonCode != reasonSelectionStale { + return fmt.Errorf( + "stale target revision requires reasonCode=%q, got %q", + reasonSelectionStale, + r.ReasonCode, + ) + } + return nil +} + +func validateHostIdentity(h *hostIdentity) error { + if !slices.Contains(allHostGOOS, h.GOOS) { + return fmt.Errorf("invalid host.goos %q", h.GOOS) + } + if !slices.Contains(allHostGOARCH, h.GOARCH) { + return fmt.Errorf("invalid host.goarch %q", h.GOARCH) + } + if !slices.Contains(allVirtualizationCapabilities, h.VirtualizationCapability) { + return fmt.Errorf("invalid host.virtualizationCapability %q", h.VirtualizationCapability) + } + return nil +} + +func validateDimensions(ctx targetContext, d dimensionSet) error { + if err := validateDimensionEnums(d); err != nil { + return err + } + if err := validatePassiveSurveyDimensions(d); err != nil { + return err + } + if err := validateUnqualifiedMSBDimensions(ctx, d); err != nil { + return err + } + if err := validateCanonicalReasonDimensions(d); err != nil { + return err + } + return validateReachabilityAndMissingDimensions(d) +} + +func validateDimensionEnums(d dimensionSet) error { + if !slices.Contains(allAvailabilityStates, d.avail) { + return fmt.Errorf("invalid availability %q", d.avail) + } + if !slices.Contains(allCompatibilityStates, d.compat) { + return fmt.Errorf("invalid compatibility %q", d.compat) + } + if !slices.Contains(allReachabilityStates, d.reach) { + return fmt.Errorf("invalid reachability %q", d.reach) + } + if !slices.Contains(allPolicyStates, d.policy) { + return fmt.Errorf("invalid policy %q", d.policy) + } + if !slices.Contains(allReasonCodes, d.reason) { + return fmt.Errorf("invalid reasonCode %q", d.reason) + } + return nil +} + +func validatePassiveSurveyDimensions(d dimensionSet) error { + if d.mode != surveyModePassive { + return nil + } + if d.executed { + return fmt.Errorf("passive survey must have executed=false") + } + if d.reach == reachabilityReachable || d.reach == reachabilityUnreachable { + return fmt.Errorf("passive survey must not report reachability=%q", d.reach) + } + if d.compat == compatibilityCompatible { + return fmt.Errorf( + "passive survey must not claim verified compatibility=%q without executing a probe", + d.compat, + ) + } + return nil +} + +func validateUnqualifiedMSBDimensions(ctx targetContext, d dimensionSet) error { + if !ctx.isCanonicalMSB || ctx.adapterSupportsT08 { + return nil + } + if d.compat == compatibilityCompatible { + return fmt.Errorf( + "unqualified microsandbox adapter lacking T08 runtime-check support cannot report compatibility=%q", + d.compat, + ) + } + if d.policy == policyManagedSelected { + return fmt.Errorf( + "unqualified microsandbox adapter lacking T08 path-pair support is not eligible for policy=%q", + d.policy, + ) + } + return nil +} + +func validateCanonicalReasonDimensions(d dimensionSet) error { + if err := validateCanonicalAvailabilityAndPolicyReason(d); err != nil { + return err + } + if err := validateCanonicalVersionReason(d); err != nil { + return err + } + return validateCanonicalProbeReason(d) +} + +func validateCanonicalAvailabilityAndPolicyReason(d dimensionSet) error { + if d.reason == reasonIncomplete && d.avail != availabilityIncomplete { + return fmt.Errorf( + "reasonCode=%q requires availability=%q, got %q", + reasonIncomplete, + availabilityIncomplete, + d.avail, + ) + } + if d.reason == reasonPathInvalid && d.avail == availabilityAvailable { + return fmt.Errorf( + "reasonCode=%q cannot report availability=%q", + reasonPathInvalid, + availabilityAvailable, + ) + } + if d.reason == reasonPlatformUnsupported && d.policy != policyUnsupported { + return fmt.Errorf( + "reasonCode=%q requires policy=%q, got %q", + reasonPlatformUnsupported, + policyUnsupported, + d.policy, + ) + } + return nil +} + +func validateCanonicalVersionReason(d dimensionSet) error { + expectedCompat, ok := requiredCompatibilityForReason(d.reason) + if !ok { + return nil + } + if d.avail != availabilityAvailable || d.compat != expectedCompat { + return fmt.Errorf( + "reasonCode=%q requires availability=%q and compatibility=%q", + d.reason, + availabilityAvailable, + expectedCompat, + ) + } + return nil +} + +func requiredCompatibilityForReason(r reasonCode) (compatibilityState, bool) { + switch r { + case reasonReady: + return compatibilityCompatible, true + case reasonVersionIncompatible: + return compatibilityIncompatible, true + case reasonVersionUnknown: + return compatibilityUnknown, true + default: + return "", false + } +} + +func validateCanonicalProbeReason(d dimensionSet) error { + if d.reason == reasonAuthRequired { + return validateAuthRequiredReason(d) + } + if d.reason == reasonProbeTimeout && !isActiveProbeAvailable(d) { + return fmt.Errorf( + "reasonCode=%q requires active_probe, executed=true, and availability=%q", + reasonProbeTimeout, + availabilityAvailable, + ) + } + return nil +} + +func validateAuthRequiredReason(d dimensionSet) error { + if d.avail != availabilityAvailable { + return fmt.Errorf( + "reasonCode=%q requires availability=%q, got %q", + reasonAuthRequired, + availabilityAvailable, + d.avail, + ) + } + if d.reach == reachabilityReachable { + return fmt.Errorf( + "reasonCode=%q cannot report reachability=%q", + reasonAuthRequired, + reachabilityReachable, + ) + } + if !d.executed && !hasUnexecutedUnknownState(d) { + return fmt.Errorf( + "unexecuted reasonCode=%q requires compatibility=%q and reachability=%q", + reasonAuthRequired, + compatibilityUnknown, + reachabilityNotChecked, + ) + } + return nil +} + +func hasUnexecutedUnknownState(d dimensionSet) bool { + return d.compat == compatibilityUnknown && d.reach == reachabilityNotChecked +} + +func isActiveProbeAvailable(d dimensionSet) bool { + return isActiveProbeExecution(d) && d.avail == availabilityAvailable +} + +func isActiveProbeExecution(d dimensionSet) bool { + return d.executed && d.mode == surveyModeActiveProbe +} + +func validateReachabilityAndMissingDimensions(d dimensionSet) error { + if err := validateUnreachableDimensions(d); err != nil { + return err + } + return validateMissingDimensions(d) +} + +func validateUnreachableDimensions(d dimensionSet) error { + if !isUnreachableStateOrReason(d) { + return nil + } + if d.avail != availabilityAvailable { + return fmt.Errorf( + "stopped/unreachable runtime must report availability=%q, got %q", + availabilityAvailable, + d.avail, + ) + } + if d.reach != reachabilityUnreachable { + return fmt.Errorf( + "reasonCode=%q requires reachability=%q, got %q", + reasonRuntimeUnreachable, + reachabilityUnreachable, + d.reach, + ) + } + if !isActiveProbeExecution(d) { + return fmt.Errorf( + "stopped/unreachable runtime requires surveyMode=%q and executed=true", + surveyModeActiveProbe, + ) + } + return nil +} + +func isUnreachableStateOrReason(d dimensionSet) bool { + return d.reach == reachabilityUnreachable || d.reason == reasonRuntimeUnreachable +} + +func validateMissingDimensions(d dimensionSet) error { + if d.avail != availabilityMissing { + return nil + } + if d.reach == reachabilityReachable || d.reach == reachabilityUnreachable { + return fmt.Errorf("missing dependency cannot report reachability=%q", d.reach) + } + if d.reason == reasonRuntimeUnreachable || d.reason == reasonReady { + return fmt.Errorf("missing dependency cannot report reasonCode=%q", d.reason) + } + return nil +} + +func validateManagedRecipe(ctx targetContext) error { + if err := validateRecipePolicyEligibility(ctx); err != nil { + return err + } + r := ctx.report + if r.ManagedRecipe == nil { + return nil + } + if err := validateRecipeFields(r); err != nil { + return err + } + if err := validateRecipeBlockingGates(r.ManagedRecipe, ctx.adapterSupportsT08); err != nil { + return err + } + return validateRecipeBundlePaths(r.ManagedRecipe) +} + +func validateRecipePolicyEligibility(ctx targetContext) error { + r := ctx.report + if isManagedPolicyOrRecipePresent(r) && !ctx.isCanonicalMSB { + return fmt.Errorf( + "managed policy and recipes are restricted to canonical external microsandbox source %q, got %q", + canonicalMicroSandboxRepo, + r.Target.ProviderSourceID, + ) + } + if err := validateUnsupportedPolicyRecipe(r); err != nil { + return err + } + if err := validateManagedAllowedRecipe(ctx); err != nil { + return err + } + return validateOfflineMissingRecipe(ctx) +} + +func isManagedPolicyOrRecipePresent(r *reportContract) bool { + return r.Policy == policyManagedAllowed || r.Policy == policyManagedSelected || + r.ManagedRecipe != nil +} + +func validateUnsupportedPolicyRecipe(r *reportContract) error { + if r.Policy != policyUnsupported { + return nil + } + if r.ManagedRecipe != nil { + return fmt.Errorf("unsupported host policy must not attach a managedRecipe") + } + if r.ReasonCode != reasonPlatformUnsupported { + return fmt.Errorf( + "policy=%q requires reasonCode=%q, got %q", + policyUnsupported, + reasonPlatformUnsupported, + r.ReasonCode, + ) + } + return nil +} + +func validateManagedAllowedRecipe(ctx targetContext) error { + r := ctx.report + if r.Policy != policyManagedAllowed { + return nil + } + if r.ManagedRecipe == nil { + return fmt.Errorf("policy=%q requires a managedRecipe definition", policyManagedAllowed) + } + if !ctx.adapterSupportsT08 && !isAllowedUntestedManagedReason(r.ReasonCode) { + return fmt.Errorf( + "prospective managed_allowed report on adapter %q without T08 support must report reasonCode=%q or %q", + r.Target.AdapterVersion, + reasonRecipeUnqualified, + reasonOfflineAssetMissing, + ) + } + return nil +} + +func isAllowedUntestedManagedReason(rc reasonCode) bool { + return rc == reasonRecipeUnqualified || rc == reasonOfflineAssetMissing +} + +func validateOfflineMissingRecipe(ctx targetContext) error { + if ctx.report.ReasonCode != reasonOfflineAssetMissing { + return nil + } + if !hasDisabledCanonicalMSBRecipe(ctx) { + return fmt.Errorf( + "reasonCode=%q requires a canonical MicroSandbox target with a disabled prospective managedRecipe", + reasonOfflineAssetMissing, + ) + } + return nil +} + +func hasDisabledCanonicalMSBRecipe(ctx targetContext) bool { + r := ctx.report + return ctx.isCanonicalMSB && r.ManagedRecipe != nil && !r.ManagedRecipe.Enabled +} + +func validateRecipeFields(r *reportContract) error { + mr := r.ManagedRecipe + if strings.TrimSpace(mr.RecipeID) == "" || strings.TrimSpace(mr.Tuple) == "" { + return fmt.Errorf("managedRecipe.recipeId and tuple are required") + } + expectedTuple := r.Host.GOOS + "/" + r.Host.GOARCH + if mr.Tuple != expectedTuple { + return fmt.Errorf("managedRecipe.tuple %q must match host %q", mr.Tuple, expectedTuple) + } + if mr.ArchiveLayout != flatArchiveLayoutPolicy { + return fmt.Errorf( + "managedRecipe.archiveLayout must be %q, got %q", + flatArchiveLayoutPolicy, + mr.ArchiveLayout, + ) + } + if !slices.Contains(allQualificationStates, mr.QualificationState) { + return fmt.Errorf("invalid managedRecipe.qualificationState %q", mr.QualificationState) + } + if mr.Enabled { + return fmt.Errorf( + "managedRecipe %q cannot be enabled before qualification gates pass", + mr.RecipeID, + ) + } + if mr.QualificationState == qualQualified { + return fmt.Errorf( + "managedRecipe %q cannot claim qualificationState=qualified in T00a baseline", + mr.RecipeID, + ) + } + return nil +} + +func validateRecipeBlockingGates(mr *managedRecipeStatus, adapterSupportsT08 bool) error { + if err := validateGateListAndG01(mr, adapterSupportsT08); err != nil { + return err + } + if err := validateLinuxAndDarwinTupleGates(mr); err != nil { + return err + } + return validateNonInitialTupleGates(mr) +} + +func validateGateListAndG01(mr *managedRecipeStatus, adapterSupportsT08 bool) error { + if len(mr.BlockingGates) == 0 { + return fmt.Errorf("disabled managedRecipe %q must list blockingGates", mr.RecipeID) + } + for _, g := range mr.BlockingGates { + if !slices.Contains(allGateIDs, g) { + return fmt.Errorf("managedRecipe.blockingGates contains unknown gate %q", g) + } + } + if !adapterSupportsT08 && !slices.Contains(mr.BlockingGates, gateG01) { + return fmt.Errorf( + "managedRecipe %q must include G01 in blockingGates while adapter lacks T08 support", + mr.RecipeID, + ) + } + return nil +} + +func validateLinuxAndDarwinTupleGates(mr *managedRecipeStatus) error { + if strings.HasPrefix(mr.Tuple, "linux/") { + if !slices.Contains(mr.BlockingGates, gateG04) { + return fmt.Errorf( + "linux managedRecipe %q must include G04 in blockingGates", + mr.RecipeID, + ) + } + if slices.Contains(mr.BlockingGates, gateG03) { + return fmt.Errorf("linux managedRecipe %q must not list macOS gate G03", mr.RecipeID) + } + } + if strings.HasPrefix(mr.Tuple, "darwin/") { + if !slices.Contains(mr.BlockingGates, gateG03) { + return fmt.Errorf( + "darwin managedRecipe %q must include G03 in blockingGates", + mr.RecipeID, + ) + } + if slices.Contains(mr.BlockingGates, gateG04) { + return fmt.Errorf("darwin managedRecipe %q must not list Linux gate G04", mr.RecipeID) + } + } + return nil +} + +func validateNonInitialTupleGates(mr *managedRecipeStatus) error { + if slices.Contains(mr.BlockingGates, gateG05) { + return fmt.Errorf( + "single-version recipe %q must not list two-version update gate G05", + mr.RecipeID, + ) + } + if slices.Contains(mr.BlockingGates, gateG08) { + return fmt.Errorf("recipe %q must not list Desktop/CLI version skew gate G08", mr.RecipeID) + } + return nil +} + +func validateRecipeBundlePaths(mr *managedRecipeStatus) error { + if mr.IllustrativeBundleRoot != "" { + if err := validateCleanAbsoluteSlashPath( + mr.IllustrativeBundleRoot, + "managedRecipe.illustrativeBundleRoot", + ); err != nil { + return err + } + } + if len(mr.ExpectedFiles) == 0 { + return fmt.Errorf("managedRecipe.expectedFiles must not be empty") + } + for _, f := range mr.ExpectedFiles { + if err := validateFlatFilename(f, "managedRecipe.expectedFiles"); err != nil { + return err + } + } + return nil +} + +func validateItem(ctx targetContext, item *dependencyItemReport) error { + if strings.TrimSpace(item.ID) == "" || strings.TrimSpace(item.DisplayName) == "" { + return fmt.Errorf("item id and displayName are required") + } + if err := validateDimensions(ctx, itemDimensions(ctx.report, item)); err != nil { + return err + } + if err := validateSelectedPair(ctx, item); err != nil { + return err + } + for i := range item.Candidates { + if err := validateCandidate(ctx, item, &item.Candidates[i]); err != nil { + return fmt.Errorf("candidates[%d]: %w", i, err) + } + } + return nil +} + +func validateSelectedPair(ctx targetContext, item *dependencyItemReport) error { + if item.SelectedPair == nil { + return nil + } + if item.ReasonCode == reasonConfigurationConflict { + return fmt.Errorf("configuration conflict item must not report a selectedPair") + } + if !ctx.isCanonicalMSB { + return fmt.Errorf("selectedPair is only valid for canonical MicroSandbox targets") + } + sp := item.SelectedPair + if !hasAllSelectedPairPaths(sp) { + return fmt.Errorf("selectedPair requires non-empty lexical and resolved paths") + } + if !slices.Contains(allCandidateSourceKinds, sp.SourceKind) { + return fmt.Errorf("invalid selectedPair.sourceKind %q", sp.SourceKind) + } + if sp.SourceKind == candidateSourceIndirectLauncher { + return fmt.Errorf("selectedPair must not use an indirect_launcher source") + } + return validateSelectedPairManagedStore(ctx, sp) +} + +func hasAllSelectedPairPaths(sp *selectedMicroSandboxPair) bool { + return strings.TrimSpace(sp.MSBLexicalPath) != "" && + strings.TrimSpace(sp.MSBResolvedPath) != "" && + strings.TrimSpace(sp.LibkrunfwLexicalPath) != "" && + strings.TrimSpace(sp.LibkrunfwResolvedPath) != "" +} + +func validateSelectedPairManagedStore(ctx targetContext, sp *selectedMicroSandboxPair) error { + if sp.SourceKind != candidateSourceManagedStore { + return nil + } + if !ctx.adapterSupportsT08 { + return fmt.Errorf("selectedPair cannot use managed_store before T08/G01 qualification") + } + mr := ctx.report.ManagedRecipe + if err := validateManagedStoreBundleEntry( + mr, + sp.MSBLexicalPath, + sp.MSBResolvedPath, + false, + ); err != nil { + return err + } + return validateManagedStoreBundleEntry( + mr, + sp.LibkrunfwLexicalPath, + sp.LibkrunfwResolvedPath, + false, + ) +} + +func validateCandidate( + ctx targetContext, + item *dependencyItemReport, + c *candidateObservation, +) error { + if err := validateCandidateIdentity(c); err != nil { + return err + } + if err := validateCandidateEnumsAndMode(ctx, c); err != nil { + return err + } + if err := validateCandidateOptionAndPath(c); err != nil { + return err + } + if err := validateCandidateObservation(ctx, c); err != nil { + return err + } + if err := validateCandidateSelectionAndCompat(ctx, item, c); err != nil { + return err + } + return validateCandidateSourceRules(ctx, c) +} + +func validateCandidateIdentity(c *candidateObservation) error { + if strings.TrimSpace(c.Component) == "" { + return fmt.Errorf("candidate.component is required") + } + if strings.TrimSpace(c.LexicalPath) == "" { + return fmt.Errorf("candidate.lexicalPath is required") + } + if !slices.Contains(allCandidateSourceKinds, c.SourceKind) { + return fmt.Errorf("invalid candidate.sourceKind %q", c.SourceKind) + } + return nil +} + +func validateCandidateEnumsAndMode(ctx targetContext, c *candidateObservation) error { + if !slices.Contains(allAvailabilityStates, c.Availability) { + return fmt.Errorf("invalid candidate.availability %q", c.Availability) + } + if !slices.Contains(allCompatibilityStates, c.Compatibility) { + return fmt.Errorf("invalid candidate.compatibility %q", c.Compatibility) + } + if !slices.Contains(allReasonCodes, c.ReasonCode) { + return fmt.Errorf("invalid candidate.reasonCode %q", c.ReasonCode) + } + if ctx.report.SurveyMode == surveyModePassive && c.Executed { + return fmt.Errorf("passive survey candidate %q must have executed=false", c.LexicalPath) + } + return nil +} + +func validateCandidateOptionAndPath(c *candidateObservation) error { + if requiresCandidateOptionName(c.SourceKind) && strings.TrimSpace(c.OptionName) == "" { + return fmt.Errorf("candidate sourceKind=%q requires non-empty optionName", c.SourceKind) + } + if c.Availability == availabilityAvailable && strings.TrimSpace(c.ResolvedPath) == "" { + return fmt.Errorf("available candidate %q must record resolvedPath", c.LexicalPath) + } + return nil +} + +func validateCandidateObservation(ctx targetContext, c *candidateObservation) error { + if c.Availability == availabilityMissing { + return validateMissingCandidateObservation(c) + } + if c.Availability != availabilityAvailable { + return nil + } + return validateAvailableCandidateObservation(ctx, c) +} + +func validateMissingCandidateObservation(c *candidateObservation) error { + if c.Observation != nil { + return fmt.Errorf( + "missing candidate %q must not fabricate an observation record", + c.LexicalPath, + ) + } + return nil +} + +func validateAvailableCandidateObservation(ctx targetContext, c *candidateObservation) error { + if c.Observation == nil || strings.TrimSpace(c.Observation.FileIdentity) == "" { + return fmt.Errorf( + "available candidate %q must record non-empty observation.fileIdentity", + c.LexicalPath, + ) + } + if err := validateOpaqueFileIdentity(&ctx.report.Target, c); err != nil { + return err + } + if !c.Executed && strings.TrimSpace(c.Observation.ObservedVersion) != "" { + return fmt.Errorf( + "passive candidate %q (executed=false) must not claim observation.observedVersion %q without an authorized probe", + c.LexicalPath, + c.Observation.ObservedVersion, + ) + } + return nil +} + +func validateOpaqueFileIdentity(t *targetIdentity, c *candidateObservation) error { + fid := c.Observation.FileIdentity + if fid == c.LexicalPath || fid == c.ResolvedPath { + return fmt.Errorf( + "candidate %q observation.fileIdentity %q must be distinct from lexicalPath and resolvedPath", + c.LexicalPath, + fid, + ) + } + if isTargetRevisionCollision(t, fid) { + return fmt.Errorf( + "candidate %q observation.fileIdentity %q must be distinct from target config/provider revisions", + c.LexicalPath, + fid, + ) + } + return nil +} + +func isTargetRevisionCollision(t *targetIdentity, fid string) bool { + if fid == t.ConfigRevision || fid == t.ProviderConfigRevision { + return true + } + return t.StaleAgainstRevision != "" && fid == t.StaleAgainstRevision +} + +func requiresCandidateOptionName(sk candidateSourceKind) bool { + return sk == candidateSourceExplicitOption || sk == candidateSourceExplicitEnv +} + +func validateCandidateSelectionAndCompat( + ctx targetContext, + item *dependencyItemReport, + c *candidateObservation, +) error { + if c.Selected && c.Availability != availabilityAvailable { + return fmt.Errorf("selected candidate %q must have availability=available", c.LexicalPath) + } + if item.ReasonCode == reasonConfigurationConflict && c.Selected { + return fmt.Errorf("configuration conflict item must not select candidate %q", c.LexicalPath) + } + if ctx.isCanonicalMSB && !ctx.adapterSupportsT08 && c.Compatibility == compatibilityCompatible { + return fmt.Errorf( + "candidate %q on unqualified microsandbox adapter cannot claim compatible", + c.LexicalPath, + ) + } + return validateUnexecutedCandidateCompat(c) +} + +// validateUnexecutedCandidateCompat applies per candidate, not per report: an +// active report may still contain candidates that were never probed. +func validateUnexecutedCandidateCompat(c *candidateObservation) error { + if c.Executed || c.Compatibility != compatibilityCompatible { + return nil + } + return fmt.Errorf( + "unexecuted candidate %q (executed=false) must not claim verified compatibility=%q", + c.LexicalPath, + c.Compatibility, + ) +} + +func validateCandidateSourceRules(ctx targetContext, c *candidateObservation) error { + if err := validateIndirectLauncherCandidate(c); err != nil { + return err + } + if err := validateOfflineMissingCandidate(ctx, c); err != nil { + return err + } + return validateManagedStoreCandidate(ctx, c) +} + +func validateIndirectLauncherCandidate(c *candidateObservation) error { + if c.SourceKind != candidateSourceIndirectLauncher { + return nil + } + if c.Selected { + return fmt.Errorf("indirect launcher candidate %q must not be selected", c.LexicalPath) + } + if c.ReasonCode != reasonIndirectLauncher { + return fmt.Errorf( + "indirect launcher candidate %q must use reasonCode=%q, got %q", + c.LexicalPath, + reasonIndirectLauncher, + c.ReasonCode, + ) + } + return nil +} + +func validateOfflineMissingCandidate(ctx targetContext, c *candidateObservation) error { + if c.ReasonCode != reasonOfflineAssetMissing { + return nil + } + if !ctx.isCanonicalMSB || c.SourceKind != candidateSourceManagedStore || + c.Availability != availabilityMissing { + return fmt.Errorf( + "reasonCode=%q is valid only for missing managed_store candidates on canonical MicroSandbox targets", + reasonOfflineAssetMissing, + ) + } + return nil +} + +func validateManagedStoreCandidate(ctx targetContext, c *candidateObservation) error { + if c.SourceKind != candidateSourceManagedStore { + return nil + } + if !ctx.isCanonicalMSB { + return fmt.Errorf( + "managed_store candidate is valid only for canonical MicroSandbox targets", + ) + } + if !ctx.adapterSupportsT08 && (c.Selected || c.Availability == availabilityAvailable) { + return fmt.Errorf( + "managed_store candidate %q cannot be available or selected before T08/G01 qualification", + c.LexicalPath, + ) + } + return validateManagedStoreBundleEntry( + ctx.report.ManagedRecipe, + c.LexicalPath, + c.ResolvedPath, + c.IsSymlink, + ) +} + +func validateManagedStoreBundleEntry( + mr *managedRecipeStatus, + lexicalPath, resolvedPath string, + isSymlink bool, +) error { + if err := validateManagedStoreLexicalEntry(mr, lexicalPath, isSymlink); err != nil { + return err + } + return validateManagedStoreResolvedEntry(lexicalPath, resolvedPath) +} + +func validateManagedStoreLexicalEntry( + mr *managedRecipeStatus, + lexicalPath string, + isSymlink bool, +) error { + if isSymlink { + return fmt.Errorf( + "managed_store candidate %q must not be a symlink (Addendum section 5)", + lexicalPath, + ) + } + if mr == nil || strings.TrimSpace(mr.IllustrativeBundleRoot) == "" { + return fmt.Errorf( + "managed_store candidate %q requires managedRecipe.illustrativeBundleRoot", + lexicalPath, + ) + } + if err := validateCleanAbsoluteSlashPath(lexicalPath, "managed_store lexicalPath"); err != nil { + return err + } + root := strings.TrimSuffix(mr.IllustrativeBundleRoot, "/") + prefix := root + "/" + if !strings.HasPrefix(lexicalPath, prefix) { + return fmt.Errorf( + "managed_store candidate %q must reside directly under illustrativeBundleRoot %q", + lexicalPath, + mr.IllustrativeBundleRoot, + ) + } + rel := strings.TrimPrefix(lexicalPath, prefix) + if err := validateFlatFilename(rel, "managed_store bundle-relative entry"); err != nil { + return fmt.Errorf( + "managed_store candidate %q must use flat bundle layout: %w", + lexicalPath, + err, + ) + } + if !slices.Contains(mr.ExpectedFiles, rel) { + return fmt.Errorf( + "managed_store bundle-relative entry %q is not listed in managedRecipe.expectedFiles %v", + rel, + mr.ExpectedFiles, + ) + } + return nil +} + +func validateManagedStoreResolvedEntry(lexicalPath, resolvedPath string) error { + if resolvedPath == "" { + return nil + } + if err := validateCleanAbsoluteSlashPath( + resolvedPath, + "managed_store resolvedPath", + ); err != nil { + return err + } + if resolvedPath != lexicalPath { + return fmt.Errorf( + "managed_store candidate %q must not resolve through a link to %q", + lexicalPath, + resolvedPath, + ) + } + return nil +} + +func validateCleanAbsoluteSlashPath(p, field string) error { + if !strings.HasPrefix(p, "/") || strings.Contains(p, "\\") { + return fmt.Errorf("%s %q must be a clean absolute slash path", field, p) + } + segments := strings.Split(p, "/") + if slices.ContainsFunc(segments[1:], isInvalidPathSegment) { + return fmt.Errorf( + "%s %q must not contain empty, dot, or parent path segments", + field, + p, + ) + } + return nil +} + +func isInvalidPathSegment(seg string) bool { + return seg == "" || seg == "." || seg == ".." +} + +func validateFlatFilename(name, field string) error { + if strings.TrimSpace(name) == "" { + return fmt.Errorf("%s must not be empty", field) + } + if name == "." || name == ".." { + return fmt.Errorf("%s %q must not be dot or parent segment", field, name) + } + if strings.Contains(name, "/") || strings.Contains(name, "\\") { + return fmt.Errorf("%s %q must be flat without subdirectory separators", field, name) + } + return nil +} + +func validateAction(ctx targetContext, a *remediationAction) error { + if err := validateActionHeaderAndAuth(a); err != nil { + return err + } + if err := validateActionEnablement(ctx, a); err != nil { + return err + } + return validateDisabledActionReason(ctx, a) +} + +func validateActionHeaderAndAuth(a *remediationAction) error { + if !slices.Contains(allActionKinds, a.Kind) { + return fmt.Errorf("invalid action kind %q", a.Kind) + } + if strings.TrimSpace(a.Label) == "" { + return fmt.Errorf("action label is required") + } + if isMutatingAction(a.Kind) && !a.RequiresEffectAuthorization { + return fmt.Errorf("mutating action %q must set requiresEffectAuthorization=true", a.Kind) + } + if requiresUserConfirmation(a.Kind) && !a.RequiresConfirmation { + return fmt.Errorf("action %q must set requiresConfirmation=true", a.Kind) + } + return nil +} + +func isMutatingAction(k actionKind) bool { + return k == actionInstall || k == actionRepair || k == actionSelect || k == actionRemove +} + +func requiresUserConfirmation(k actionKind) bool { + return k == actionInstall || k == actionSelect || k == actionRemove +} + +func validateActionEnablement(ctx targetContext, a *remediationAction) error { + if !a.Enabled { + return nil + } + if err := validateEnabledActionTargetAndRecipe(ctx.report, a); err != nil { + return err + } + return validateEnabledActionAdapterAndSelect(ctx, a) +} + +func validateEnabledActionTargetAndRecipe(r *reportContract, a *remediationAction) error { + if isStaleTarget(&r.Target) && isMutatingAction(a.Kind) { + return fmt.Errorf("stale target report must not enable mutating action %q", a.Kind) + } + if a.Kind == actionInstall || a.Kind == actionRepair { + return fmt.Errorf( + "managed action %q cannot be enabled while all recipes remain unqualified", + a.Kind, + ) + } + return nil +} + +func validateEnabledActionAdapterAndSelect(ctx targetContext, a *remediationAction) error { + r := ctx.report + if ctx.isCanonicalMSB && !ctx.adapterSupportsT08 && isMutatingAction(a.Kind) { + return fmt.Errorf( + "mutating action %q cannot be enabled for MicroSandbox adapter %q lacking T08 support (G01)", + a.Kind, + r.Target.AdapterVersion, + ) + } + if isSelectBlockedByAvailability(r.Availability, a.Kind) { + return fmt.Errorf("select action cannot be enabled when availability is %q", r.Availability) + } + return nil +} + +func isStaleTarget(t *targetIdentity) bool { + return t.StaleAgainstRevision != "" && t.StaleAgainstRevision != t.ProviderConfigRevision +} + +func isSelectBlockedByAvailability(avail availabilityState, kind actionKind) bool { + return kind == actionSelect && (avail == availabilityMissing || avail == availabilityIncomplete) +} + +func validateDisabledActionReason(ctx targetContext, a *remediationAction) error { + if a.Enabled { + if a.DisabledReasonCode != "" { + return fmt.Errorf( + "enabled action %q must not specify disabledReasonCode %q", + a.Kind, + a.DisabledReasonCode, + ) + } + return nil + } + if a.DisabledReasonCode == "" { + return fmt.Errorf("disabled action %q must specify disabledReasonCode", a.Kind) + } + if !slices.Contains(allReasonCodes, a.DisabledReasonCode) { + return fmt.Errorf("invalid disabledReasonCode %q", a.DisabledReasonCode) + } + if a.DisabledReasonCode == reasonOfflineAssetMissing && !hasDisabledCanonicalMSBRecipe(ctx) { + return fmt.Errorf( + "disabledReasonCode=%q requires a canonical MicroSandbox target with a disabled managedRecipe", + reasonOfflineAssetMissing, + ) + } + return nil +} + +func buildPassiveAuthRequiredReport(t *testing.T, external *reportContract) *reportContract { + t.Helper() + r := cloneReport(t, external) + r.SurveyMode = surveyModePassive + r.Executed = false + r.Compatibility = compatibilityUnknown + r.Reachability = reachabilityNotChecked + r.ReasonCode = reasonAuthRequired + + r.Items[0].Executed = false + r.Items[0].Compatibility = compatibilityUnknown + r.Items[0].Reachability = reachabilityNotChecked + r.Items[0].ReasonCode = reasonAuthRequired + + r.Items[0].Candidates[0].Executed = false + r.Items[0].Candidates[0].Compatibility = compatibilityUnknown + r.Items[0].Candidates[0].ReasonCode = reasonAuthRequired + r.Items[0].Candidates[0].Observation.ObservedVersion = "" + return r +} + +func buildRootAndRecipeDeletionCases(managedRaw []byte) []rawShapeCase { + return []rawShapeCase{ + { + name: "missing root executed boolean", + base: managedRaw, + mutate: func(doc map[string]any) { delete(doc, "executed") }, + errSub: `$: missing required field "executed"`, + }, + { + name: "missing target.trustedBuiltinIdentity boolean", + base: managedRaw, + mutate: func(doc map[string]any) { + delete(doc["target"].(map[string]any), "trustedBuiltinIdentity") + }, + errSub: `$.target: missing required field "trustedBuiltinIdentity"`, + }, + { + name: "missing managedRecipe.enabled boolean", + base: managedRaw, + mutate: func(doc map[string]any) { + delete(doc["managedRecipe"].(map[string]any), "enabled") + }, + errSub: `$.managedRecipe: missing required field "enabled"`, + }, + { + name: "missing managedRecipe.blockingGates array", + base: managedRaw, + mutate: func(doc map[string]any) { + delete(doc["managedRecipe"].(map[string]any), "blockingGates") + }, + errSub: `$.managedRecipe: missing required field "blockingGates"`, + }, + { + name: "missing item.required boolean", + base: managedRaw, + mutate: func(doc map[string]any) { + delete(firstItemMap(doc), "required") + }, + errSub: `$.items[0]: missing required field "required"`, + }, + { + name: "missing item.executed boolean", + base: managedRaw, + mutate: func(doc map[string]any) { + delete(firstItemMap(doc), "executed") + }, + errSub: `$.items[0]: missing required field "executed"`, + }, + } +} + +func buildItemAndActionDeletionCases(managedRaw, staleRaw []byte) []rawShapeCase { + return []rawShapeCase{ + { + name: "missing candidate.executed boolean", + base: managedRaw, + mutate: func(doc map[string]any) { + delete(firstCandidateMap(doc), "executed") + }, + errSub: `$.items[0].candidates[0]: missing required field "executed"`, + }, + { + name: "missing candidate.selected boolean", + base: managedRaw, + mutate: func(doc map[string]any) { + delete(firstCandidateMap(doc), "selected") + }, + errSub: `$.items[0].candidates[0]: missing required field "selected"`, + }, + { + name: "missing selectedPair.sourceKind", + base: staleRaw, + mutate: func(doc map[string]any) { + pair := firstItemMap(doc)["selectedPair"].(map[string]any) + delete(pair, "sourceKind") + }, + errSub: `$.items[0].selectedPair: missing required field "sourceKind"`, + }, + { + name: "missing action.enabled boolean", + base: managedRaw, + mutate: func(doc map[string]any) { + delete(firstActionMap(doc), "enabled") + }, + errSub: `$.actions[0]: missing required field "enabled"`, + }, + { + name: "missing action.requiresEffectAuthorization boolean", + base: managedRaw, + mutate: func(doc map[string]any) { + delete(firstActionMap(doc), "requiresEffectAuthorization") + }, + errSub: `$.actions[0]: missing required field "requiresEffectAuthorization"`, + }, + { + name: "missing action.requiresConfirmation boolean", + base: managedRaw, + mutate: func(doc map[string]any) { + delete(firstActionMap(doc), "requiresConfirmation") + }, + errSub: `$.actions[0]: missing required field "requiresConfirmation"`, + }, + } +} + +func buildTypeAndUnknownFieldCases(managedRaw []byte) []rawShapeCase { + return []rawShapeCase{ + { + name: "wrong scalar type for root executed", + base: managedRaw, + mutate: func(doc map[string]any) { doc["executed"] = "false" }, + errSub: `$.executed: expected boolean`, + }, + { + name: "wrong scalar type for schemaVersion float", + base: managedRaw, + mutate: func(doc map[string]any) { doc["schemaVersion"] = 1.5 }, + errSub: `$.schemaVersion: expected integer`, + }, + { + name: "wrong scalar type for candidate.selected", + base: managedRaw, + mutate: func(doc map[string]any) { + firstCandidateMap(doc)["selected"] = 0 + }, + errSub: `$.items[0].candidates[0].selected: expected boolean`, + }, + { + name: "wrong container type for items", + base: managedRaw, + mutate: func(doc map[string]any) { doc["items"] = map[string]any{} }, + errSub: `$.items: expected array`, + }, + { + name: "unknown root field", + base: managedRaw, + mutate: func(doc map[string]any) { doc["unexpectedRoot"] = true }, + errSub: `$: unknown field "unexpectedRoot"`, + }, + { + name: "unknown nested field in candidate", + base: managedRaw, + mutate: func(doc map[string]any) { + firstCandidateMap(doc)["extraCandidateField"] = "nope" + }, + errSub: `$.items[0].candidates[0]: unknown field "extraCandidateField"`, + }, + } +} + +func firstItemMap(doc map[string]any) map[string]any { + return doc["items"].([]any)[0].(map[string]any) +} + +func firstCandidateMap(doc map[string]any) map[string]any { + return firstItemMap(doc)["candidates"].([]any)[0].(map[string]any) +} + +func firstActionMap(doc map[string]any) map[string]any { + return doc["actions"].([]any)[0].(map[string]any) +} + +func buildNestedEnumMutationCases() []nestedCandidateMutationCase { + return []nestedCandidateMutationCase{ + { + name: "invalid selectedPair.sourceKind", + mutate: func(r *reportContract) { + r.Items[0].SelectedPair.SourceKind = candidateSourceKind("arbitrary_source") + }, + errSub: "invalid selectedPair.sourceKind", + expectSchemaErr: true, + }, + { + name: "invalid candidate.availability", + mutate: func(r *reportContract) { + r.Items[0].Candidates[0].Availability = availabilityState("bogus_avail") + }, + errSub: "invalid candidate.availability", + expectSchemaErr: true, + }, + { + name: "invalid candidate.compatibility", + mutate: func(r *reportContract) { + r.Items[0].Candidates[0].Compatibility = compatibilityState("bogus_compat") + }, + errSub: "invalid candidate.compatibility", + expectSchemaErr: true, + }, + { + name: "invalid candidate.reasonCode", + mutate: func(r *reportContract) { + r.Items[0].Candidates[0].ReasonCode = reasonCode("dependency_bogus_reason") + }, + errSub: "invalid candidate.reasonCode", + expectSchemaErr: true, + }, + } +} + +func buildMissingCandidateIdentityCases() []nestedCandidateMutationCase { + return []nestedCandidateMutationCase{ + { + name: "missing candidate.component", + mutate: func(r *reportContract) { + r.Items[0].Candidates[0].Component = "" + }, + errSub: "candidate.component is required", + expectSchemaErr: true, + }, + { + name: "missing candidate.lexicalPath", + mutate: func(r *reportContract) { + r.Items[0].Candidates[0].LexicalPath = "" + }, + errSub: "candidate.lexicalPath is required", + expectSchemaErr: true, + }, + { + name: "missing candidate.sourceKind", + mutate: func(r *reportContract) { + r.Items[0].Candidates[0].SourceKind = "" + }, + errSub: "invalid candidate.sourceKind", + expectSchemaErr: true, + }, + { + name: "explicit_option candidate missing optionName rejected semantically", + mutate: func(r *reportContract) { + r.Items[0].Candidates[0].OptionName = "" + }, + errSub: "requires non-empty optionName", + expectSchemaErr: false, + }, + } +} + +func cloneReport(t *testing.T, src *reportContract) *reportContract { + t.Helper() + raw, err := json.Marshal(src) + if err != nil { + t.Fatalf("marshal report: %v", err) + } + var dst reportContract + if err := json.Unmarshal(raw, &dst); err != nil { + t.Fatalf("unmarshal report: %v", err) + } + return &dst +} + +func toStrings[T ~string](in []T) []string { + out := make([]string, len(in)) + for i, v := range in { + out[i] = string(v) + } + return out +} + +func buildUnsupportedSchemaKeywordCases() []schemaKeywordMutationCase { + return []schemaKeywordMutationCase{ + { + name: "unsupported root validation keyword oneOf", + mutate: func(doc map[string]any) { doc["oneOf"] = []any{} }, + errSub: `$: unsupported schema keyword "oneOf"`, + }, + { + name: "unsupported property validation keyword maxLength", + mutate: func(doc map[string]any) { + props := doc["properties"].(map[string]any) + msg := props["message"].(map[string]any) + msg["maxLength"] = 256 + }, + errSub: `$.properties.message: unsupported schema keyword "maxLength"`, + }, + { + name: "unsupported nested $defs validation keyword pattern", + mutate: func(doc map[string]any) { + defs := doc["$defs"].(map[string]any) + ti := defs["targetIdentity"].(map[string]any) + props := ti["properties"].(map[string]any) + ctxName := props["contextName"].(map[string]any) + ctxName["pattern"] = "^[a-z0-9-]+$" + }, + errSub: `$.$defs.targetIdentity.properties.contextName: unsupported schema keyword "pattern"`, + }, + { + name: "unsupported array items validation keyword anyOf", + mutate: func(doc map[string]any) { + defs := doc["$defs"].(map[string]any) + mr := defs["managedRecipeStatus"].(map[string]any) + props := mr["properties"].(map[string]any) + gates := props["blockingGates"].(map[string]any) + items := gates["items"].(map[string]any) + items["anyOf"] = []any{} + }, + errSub: `$.$defs.managedRecipeStatus.properties.blockingGates.items: unsupported schema keyword "anyOf"`, + }, + } +} + +func buildIgnoredSchemaKeywordCombinationCases() []schemaKeywordMutationCase { + return []schemaKeywordMutationCase{ + { + name: "boolean property with const false rejected", + mutate: func(doc map[string]any) { + schemaRootPropertyMap(doc, "executed")["const"] = false + }, + errSub: `$.properties.executed: keyword "const" is not supported on schema type "boolean"`, + }, + { + name: "$ref property with validation sibling minLength rejected", + mutate: func(doc map[string]any) { + schemaRootPropertyMap(doc, "availability")["minLength"] = 10 + }, + errSub: `$.properties.availability: $ref node cannot combine with validation keyword "minLength"`, + }, + { + name: "$ref property with validation sibling const rejected", + mutate: func(doc map[string]any) { + schemaRootPropertyMap(doc, "availability")["const"] = "available" + }, + errSub: `$.properties.availability: $ref node cannot combine with validation keyword "const"`, + }, + { + name: "integer property with enum rejected", + mutate: func(doc map[string]any) { + schemaRootPropertyMap(doc, "schemaVersion")["enum"] = []string{"1"} + }, + errSub: `$.properties.schemaVersion: keyword "enum" is not supported on schema type "integer"`, + }, + { + name: "boolean property with minLength rejected", + mutate: func(doc map[string]any) { + schemaRootPropertyMap(doc, "executed")["minLength"] = 1 + }, + errSub: `$.properties.executed: keyword "minLength" is not supported on schema type "boolean"`, + }, + { + name: "string property with minItems rejected", + mutate: func(doc map[string]any) { + schemaRootPropertyMap(doc, "message")["minItems"] = 1 + }, + errSub: `$.properties.message: keyword "minItems" is not supported on schema type "string"`, + }, + { + name: "string property with properties rejected", + mutate: func(doc map[string]any) { + schemaRootPropertyMap(doc, "message")["properties"] = map[string]any{} + }, + errSub: `$.properties.message: keyword "properties" is not supported on schema type "string"`, + }, + } +} + +func buildInvalidSchemaConstraintValueCases() []schemaKeywordMutationCase { + return []schemaKeywordMutationCase{ + { + name: "string property with non-string const rejected", + mutate: func(doc map[string]any) { + schemaRootPropertyMap(doc, "schema")["const"] = false + }, + errSub: `$.properties.schema.const: expected string const for type "string"`, + }, + { + name: "integer property with non-integer const rejected", + mutate: func(doc map[string]any) { + schemaRootPropertyMap(doc, "schemaVersion")["const"] = "1" + }, + errSub: `$.properties.schemaVersion.const: expected integer const for type "integer"`, + }, + { + name: "integer property with fractional const rejected", + mutate: func(doc map[string]any) { + schemaRootPropertyMap(doc, "schemaVersion")["const"] = 1.5 + }, + errSub: `$.properties.schemaVersion.const: expected integer const for type "integer"`, + }, + { + name: "string property with empty enum rejected", + mutate: func(doc map[string]any) { + schemaRootPropertyMap(doc, "surveyMode")["enum"] = []string{} + }, + errSub: `$.properties.surveyMode.enum: expected non-empty string array`, + }, + { + name: "string property with negative minLength rejected", + mutate: func(doc map[string]any) { + schemaRootPropertyMap(doc, "message")["minLength"] = -1 + }, + errSub: `$.properties.message.minLength: expected non-negative integer`, + }, + { + name: "array property with negative minItems rejected", + mutate: func(doc map[string]any) { + schemaRootPropertyMap(doc, "items")["minItems"] = -1 + }, + errSub: `$.properties.items.minItems: expected non-negative integer`, + }, + } +} + +func schemaRootPropertyMap(doc map[string]any, prop string) map[string]any { + return doc["properties"].(map[string]any)[prop].(map[string]any) +} + +func buildInexactIntegerSchemaLiteralCases() []schemaLiteralCase { + const constErr = `$.const: expected integer const for type "integer"` + return []schemaLiteralCase{ + { + name: "fractional const that rounds to 1 in float64 rejected", + schema: `{"type":"integer","const":1.0000000000000001}`, + errSub: constErr, + }, + { + name: "exponent const rejected", + schema: `{"type":"integer","const":1e0}`, + errSub: constErr, + }, + { + name: "const with zero fraction rejected", + schema: `{"type":"integer","const":1.0}`, + errSub: constErr, + }, + { + name: "const beyond int64 rejected", + schema: `{"type":"integer","const":9223372036854775808}`, + errSub: constErr, + }, + { + name: "fractional minLength that rounds to 1 in float64 rejected", + schema: `{"type":"string","minLength":1.0000000000000001}`, + errSub: `$.minLength: expected non-negative integer`, + }, + { + name: "exponent minItems rejected", + schema: `{"type":"array","minItems":1e0}`, + errSub: `$.minItems: expected non-negative integer`, + }, + { + name: "negative minLength literal rejected", + schema: `{"type":"string","minLength":-1}`, + errSub: `$.minLength: expected non-negative integer`, + }, + } +} + +func buildExactIntegerValidationLiteralCases() []schemaLiteralCase { + const beyondFloat64 = `{"type":"integer","const":9007199254740993}` + const ordinaryInteger = `{"type":"integer","const":1}` + return []schemaLiteralCase{ + { + name: "const beyond float64 precision rejects adjacent integer", + schema: beyondFloat64, + input: `9007199254740992`, + errSub: `$: expected const 9007199254740993, got 9007199254740992`, + }, + { + name: "const beyond float64 precision accepts exact integer", + schema: beyondFloat64, + input: `9007199254740993`, + }, + { + name: "ordinary integer const accepts match", + schema: ordinaryInteger, + input: `1`, + }, + { + name: "ordinary integer const rejects mismatch", + schema: ordinaryInteger, + input: `2`, + errSub: `$: expected const 1, got 2`, + }, + { + name: "ordinary integer const rejects fractional input", + schema: ordinaryInteger, + input: `1.0`, + errSub: `$: expected integer`, + }, + { + name: "integer input beyond int64 rejected", + schema: `{"type":"integer"}`, + input: `9223372036854775808`, + errSub: `$: invalid integer 9223372036854775808`, + }, + } +} + +func buildUnicodeMinLengthLiteralCases() []schemaLiteralCase { + const minTwo = `{"type":"string","minLength":2}` + const belowMinTwo = `$: string length 1 is below minLength 2` + return []schemaLiteralCase{ + { + name: "one two-byte character is below minLength 2", + schema: minTwo, + input: `"\u00e9"`, + errSub: belowMinTwo, + }, + { + name: "one supplementary-plane character is below minLength 2", + schema: minTwo, + input: `"\ud83d\ude00"`, + errSub: belowMinTwo, + }, + { + name: "two accented characters satisfy minLength 2", + schema: minTwo, + input: `"\u00e9\u00e8"`, + }, + { + name: "two ASCII characters satisfy minLength 2", + schema: minTwo, + input: `"ab"`, + }, + { + name: "one ASCII character is below minLength 2", + schema: minTwo, + input: `"a"`, + errSub: belowMinTwo, + }, + { + name: "empty string satisfies minLength 0", + schema: `{"type":"string","minLength":0}`, + input: `""`, + }, + } +} diff --git a/pkg/dependencies/inspect_contracts_test.go b/pkg/dependencies/inspect_contracts_test.go new file mode 100644 index 0000000000..014cfe0662 --- /dev/null +++ b/pkg/dependencies/inspect_contracts_test.go @@ -0,0 +1,25 @@ +package dependencies_test + +import ( + "os" + "path/filepath" +) + +// TestInspectShippedCommandContracts validates retained actual-main stdout with +// the unchanged raw-schema and semantic validators. The producer is the Unix +// PTY process test in cmd, not an authored report fixture. +func (s *contractsSuite) TestInspectShippedCommandContracts() { + dir := os.Getenv("DEVSY_T10_EVIDENCE_DIR") + if dir == "" { + s.T().Skip("requires retained actual-main inspect process outputs") + } + for _, builtin := range []string{"docker", "podman", "apple", "kubernetes"} { + // #nosec G304 G703 -- explicit runner-owned evidence directory and fixed producer filenames. + raw, err := os.ReadFile(filepath.Join(dir, "report-"+builtin+".stdout")) + s.Require().NoError(err) + report, err := s.decodeAndValidateRaw(raw) + s.Require().NoError(err) + s.Equal(builtin, report.Target.ProviderType) + s.Empty(report.Actions) + } +} diff --git a/pkg/dependencies/journal.go b/pkg/dependencies/journal.go new file mode 100644 index 0000000000..9338609761 --- /dev/null +++ b/pkg/dependencies/journal.go @@ -0,0 +1,114 @@ +package dependencies + +import ( + "errors" + "slices" + "time" +) + +type JournalPhase string + +const ( + metadataPolicyBlocked = "dependency_policy_blocked" + PhasePlanned JournalPhase = "planned" + PhaseDownloading JournalPhase = "downloading" + PhaseVerifiedArchive JournalPhase = "verified_archive" + PhaseExtracting JournalPhase = "extracting" + PhasePublished JournalPhase = "published" + PhaseBinding JournalPhase = "binding" + PhaseComplete JournalPhase = "complete" + PhaseCanceled JournalPhase = "canceled" + PhaseFailed JournalPhase = "failed" + PhaseInterrupted JournalPhase = "interrupted" +) + +// Journal contains references and bounded outcome codes, never environment, +// endpoint tokens, raw diagnostic output, or a PID-based liveness assertion. +type Journal struct { + SchemaVersion int `json:"schemaVersion"` + OperationID string `json:"operationId"` + Phase JournalPhase `json:"phase"` + Artifacts []ReceiptIdentity `json:"artifacts"` + Receipts []ReceiptIdentity `json:"receipts"` + StartedAt time.Time `json:"startedAt"` + UpdatedAt time.Time `json:"updatedAt"` + Terminal *JournalTerminal `json:"terminal,omitempty"` +} + +type JournalTerminal struct { + At time.Time `json:"at"` + ReasonCode string `json:"reasonCode"` +} + +func (j Journal) validate() error { + if !metadataID(j.OperationID) || !validJournalPhase(j.Phase) { + return errors.New("invalid operation identity or journal phase") + } + if !metadataTime(j.StartedAt) || !metadataTime(j.UpdatedAt) || j.UpdatedAt.Before(j.StartedAt) { + return errors.New("invalid journal timestamps") + } + if err := j.validateReferences(); err != nil { + return err + } + return j.validateTerminal() +} + +func validJournalPhase(phase JournalPhase) bool { + return slices.Contains([]JournalPhase{ + PhasePlanned, PhaseDownloading, PhaseVerifiedArchive, PhaseExtracting, PhasePublished, + PhaseBinding, PhaseComplete, PhaseCanceled, PhaseFailed, PhaseInterrupted, + }, phase) +} + +func (j Journal) validateReferences() error { + if !boundedJournalReferences(j.Artifacts, j.Receipts) { + return errors.New("journal requires bounded artifact and receipt references") + } + if err := validateReceiptIdentities(j.Artifacts); err != nil { + return err + } + if err := validateReceiptIdentities(j.Receipts); err != nil { + return err + } + for _, receipt := range j.Receipts { + if !slices.Contains(j.Artifacts, receipt) { + return errors.New("journal receipt has no referenced artifact") + } + } + return nil +} + +func (j Journal) validateTerminal() error { + terminal := slices.Contains( + []JournalPhase{PhaseComplete, PhaseCanceled, PhaseFailed, PhaseInterrupted}, + j.Phase, + ) + if terminal != (j.Terminal != nil) { + return errors.New("terminal data must match journal phase") + } + if !terminal { + return nil + } + if !metadataTime(j.Terminal.At) || !j.Terminal.At.Equal(j.UpdatedAt) { + return errors.New("terminal time must match journal update time") + } + allowed := map[JournalPhase][]string{ + PhaseComplete: {"complete"}, + PhaseCanceled: {"canceled"}, + PhaseFailed: { + "dependency_integrity_failed", + "dependency_store_unwritable", + metadataPolicyBlocked, + }, + PhaseInterrupted: {"dependency_operation_interrupted"}, + } + if !slices.Contains(allowed[j.Phase], j.Terminal.ReasonCode) { + return errors.New("invalid terminal reason code") + } + return nil +} + +func boundedJournalReferences(artifacts, receipts []ReceiptIdentity) bool { + return len(artifacts) > 0 && len(artifacts) <= maxMetadataReferences && receipts != nil && + len(receipts) <= maxMetadataReferences +} diff --git a/pkg/dependencies/lookup.go b/pkg/dependencies/lookup.go new file mode 100644 index 0000000000..b05adc2fd8 --- /dev/null +++ b/pkg/dependencies/lookup.go @@ -0,0 +1,283 @@ +package dependencies + +import ( + "context" + "errors" + "os" + "path/filepath" + "strings" +) + +type LookupOrigin string + +const ( + LookupExplicit LookupOrigin = "explicit_option" + LookupExplicitEnv LookupOrigin = "explicit_env" + LookupPATH LookupOrigin = "external_path" + LookupReviewed LookupOrigin = "well_known_path" + LookupMissing = "dependency_missing" + LookupInvalidPath = "dependency_path_invalid" + LookupIndirectLauncher = "dependency_indirect_launcher" + LookupInspectionDeferred = "dependency_inspection_deferred" +) + +// LookupRequest contains a command name or an explicit invocation path. +// Explicit retains user intent even for an empty value or a manifest default. +// ReviewedLocations are ordered, complete absolute executable paths reviewed by +// the caller for this provider/host. They are not directories to scan. +type LookupRequest struct { + Command string + Explicit bool + // ExplicitOrigin defaults to explicit_option and may also be explicit_env. + ExplicitOrigin LookupOrigin + ReviewedLocations []string +} + +// LookupResult is filesystem evidence, not a selection or a full Survey report. +// A deferred candidate retains lexical evidence without an executable claim. +// An empty ReasonCode means at least one executable file was observed; it says +// nothing about version, compatibility, reachability, native format, or trust. +type LookupResult struct { + Candidates []ExecutableCandidate `json:"candidates"` + ReasonCode string `json:"reasonCode,omitempty"` + Executed bool `json:"executed"` +} + +// LookupExecutable performs only metadata reads on the current native OS. +// Explicit command names use only snapshot PATH, stopping at its first executable +// observation (including a shim), or at a deferred inspection. Explicit paths +// never fall back. Automatic discovery keeps ordered observations from PATH +// before reviewed locations. +func (e LookupEnvironment) LookupExecutable( + ctx context.Context, + request LookupRequest, +) (LookupResult, error) { + if !filepath.IsAbs(e.cwd) { + return LookupResult{}, errors.New("lookup requires an environment snapshot") + } + if err := ctx.Err(); err != nil { + return LookupResult{}, err + } + if request.Explicit { + return e.lookupExplicit(ctx, request) + } + if err := validateAutomaticLookup(request); err != nil { + return LookupResult{}, err + } + result, err := e.searchPATH(ctx, request.Command, LookupPATH) + if err != nil { + return LookupResult{}, err + } + for _, path := range request.ReviewedLocations { + candidate, err := e.observe(ctx, path, LookupReviewed) + if err != nil { + return LookupResult{}, err + } + result.append(candidate) + } + result.finish(false) + return result, nil +} + +func (e LookupEnvironment) lookupExplicit( + ctx context.Context, + request LookupRequest, +) (LookupResult, error) { + origin, err := request.explicitOrigin() + if err != nil { + return LookupResult{}, err + } + command := request.Command + invalid := LookupResult{ReasonCode: LookupInvalidPath} + if command == "" || strings.ContainsRune(command, 0) { + return invalid, nil + } + if commandName(command) { + result, err := e.searchPATH(ctx, command, origin) + if err != nil { + return LookupResult{}, err + } + result.finish(true) + return result, err + } + path, valid := e.absolute(command) + if !valid { + return invalid, nil + } + return e.lookupExplicitPath(ctx, path, origin) +} + +func (e LookupEnvironment) lookupExplicitPath( + ctx context.Context, + path string, + origin LookupOrigin, +) (LookupResult, error) { + result := LookupResult{} + names := e.executableNames(path) + if len(names) == 0 || names[0] != path { + names = append([]string{path}, names...) + } + for _, name := range names { + if err := ctx.Err(); err != nil { + return LookupResult{}, err + } + candidate, err := e.observe(ctx, name, origin) + if err != nil { + return LookupResult{}, err + } + result.Candidates = append(result.Candidates, candidate) + if candidate.State == FileExecutable || candidate.State == FileDeferred { + break + } + } + result.finish(true) + return result, nil +} + +func (e LookupEnvironment) searchPATH( + ctx context.Context, + command string, + origin LookupOrigin, +) (LookupResult, error) { + result := LookupResult{} + directories, err := e.pathDirectories(ctx) + if err != nil { + return LookupResult{}, err + } + for _, directory := range directories { + for _, name := range e.executableNames(command) { + candidate, err := e.observeDirectory(ctx, directory, name, origin) + if err != nil { + return LookupResult{}, err + } + result.append(candidate) + if origin != LookupPATH && + (candidate.State == FileExecutable || candidate.State == FileDeferred) { + return result, nil + } + } + } + return result, nil +} + +func (e LookupEnvironment) observeDirectory( + ctx context.Context, + directory lookupDirectory, + name string, + origin LookupOrigin, +) (ExecutableCandidate, error) { + if err := ctx.Err(); err != nil { + return ExecutableCandidate{}, err + } + path := directory.path + string(filepath.Separator) + name + if directory.deferred { + return deferredCandidate(path, origin), nil + } + return e.observe(ctx, path, origin) +} + +func (r LookupRequest) explicitOrigin() (LookupOrigin, error) { + switch r.ExplicitOrigin { + case "", LookupExplicit: + return LookupExplicit, nil + case LookupExplicitEnv: + return LookupExplicitEnv, nil + default: + return "", errors.New("invalid explicit lookup origin") + } +} + +type lookupDirectory struct { + path string + deferred bool +} + +func (e LookupEnvironment) pathDirectories(ctx context.Context) ([]lookupDirectory, error) { + if err := ctx.Err(); err != nil { + return nil, err + } + path, _ := e.Value("PATH") + var directories []lookupDirectory + for _, directory := range filepath.SplitList(path) { + if filepath.IsAbs(directory) { + directories = append(directories, lookupDirectory{path: directory}) + } + } + if len(directories) == 0 { + return nil, ctx.Err() + } + return e.excludeWorkingDirectory(ctx, directories) +} + +func (e LookupEnvironment) excludeWorkingDirectory( + ctx context.Context, + directories []lookupDirectory, +) ([]lookupDirectory, error) { + // Compare actual directory identity without cleaning away Unix link/.. traversal. + cwd, cwdErr := e.inspectFile(ctx, e.cwd) + if lookupCanceled(cwdErr) { + return nil, cwdErr + } + filtered := directories[:0] + for _, entry := range directories { + entry.deferred = cwdErr != nil + if cwdErr == nil { + observed, err := e.inspectFile(ctx, entry.path) + if lookupCanceled(err) { + return nil, err + } + entry.deferred = errors.Is(err, errLookupDeferred) + if err == nil && os.SameFile(cwd.info, observed.info) { + continue + } + } + filtered = append(filtered, entry) + } + directories = filtered + return directories, ctx.Err() +} + +func (r *LookupResult) append(candidate ExecutableCandidate) { + if candidate.State == FileMissing { + return + } + for _, existing := range r.Candidates { + if existing.LexicalPath == candidate.LexicalPath { + return + } + } + r.Candidates = append(r.Candidates, candidate) +} + +func (r *LookupResult) finish(explicit bool) { + r.ReasonCode = LookupMissing + if explicit { + r.ReasonCode = LookupInvalidPath + } + for _, candidate := range r.Candidates { + if candidate.State == FileExecutable || candidate.State == FileDeferred { + r.ReasonCode = candidate.ReasonCode + return + } + } +} + +func commandName(command string) bool { + return command != "" && command != "." && command != ".." && + !strings.ContainsRune(command, 0) && !invocationPath(command) +} + +func validateAutomaticLookup(request LookupRequest) error { + if request.ExplicitOrigin != "" { + return errors.New("automatic lookup cannot have an explicit origin") + } + if !commandName(request.Command) { + return errors.New("automatic lookup requires a command name") + } + for _, path := range request.ReviewedLocations { + if !filepath.IsAbs(path) || strings.ContainsRune(path, 0) { + return errors.New("reviewed executable location must be absolute") + } + } + return nil +} diff --git a/pkg/dependencies/lookup_environment.go b/pkg/dependencies/lookup_environment.go new file mode 100644 index 0000000000..3d174722b2 --- /dev/null +++ b/pkg/dependencies/lookup_environment.go @@ -0,0 +1,77 @@ +package dependencies + +import ( + "context" + "errors" + "maps" + "path/filepath" + "runtime" + "strings" +) + +// LookupEnvironment is an immutable, already-effective invocation snapshot. +// Its zero value is invalid. It never fills absent values from the process. +type LookupEnvironment struct { + values map[string]string + cwd string + inspect func(context.Context, string) (lookupFile, error) +} + +func NewLookupEnvironment(values map[string]string, cwd string) (LookupEnvironment, error) { + if !filepath.IsAbs(cwd) || strings.ContainsRune(cwd, 0) { + return LookupEnvironment{}, errors.New("lookup working directory must be absolute") + } + copied := maps.Clone(values) + if runtime.GOOS == lookupWindows { + copied = make(map[string]string, len(values)) + for key, value := range values { + key = strings.ToUpper(key) + if _, exists := copied[key]; exists { + return LookupEnvironment{}, errors.New("ambiguous Windows environment key") + } + copied[key] = value + } + } + return LookupEnvironment{values: copied, cwd: cwd}, nil +} + +func (e LookupEnvironment) Value(key string) (string, bool) { + if runtime.GOOS == lookupWindows { + key = strings.ToUpper(key) + } + value, present := e.values[key] + return value, present +} + +func (e LookupEnvironment) WorkingDirectory() string { return e.cwd } + +// absolute preserves symlink/.. traversal semantics rather than cleaning it away. +func (e LookupEnvironment) absolute(path string) (string, bool) { + if filepath.IsAbs(path) { + return path, true + } + // Drive-relative and root-relative Windows paths depend on ambient drive state. + if filepath.VolumeName(path) != "" || + (runtime.GOOS == lookupWindows && strings.HasPrefix(path, `\`)) { + return "", false + } + if runtime.GOOS == lookupWindows && strings.HasPrefix(path, "/") { + return "", false + } + return e.cwd + string(filepath.Separator) + path, true +} + +func (e LookupEnvironment) inspectFile(ctx context.Context, path string) (lookupFile, error) { + if err := ctx.Err(); err != nil { + return lookupFile{}, err + } + inspect := e.inspect + if inspect == nil { + inspect = inspectLookupFile + } + observed, err := inspect(ctx, path) + if canceled := ctx.Err(); canceled != nil { + return lookupFile{}, canceled + } + return observed, err +} diff --git a/pkg/dependencies/lookup_observe.go b/pkg/dependencies/lookup_observe.go new file mode 100644 index 0000000000..7d7a0a8003 --- /dev/null +++ b/pkg/dependencies/lookup_observe.go @@ -0,0 +1,133 @@ +package dependencies + +import ( + "context" + "errors" + "io/fs" + "os" + "runtime" +) + +type FileState string + +// FileExecutable means observed execute bits on Unix or an invocation suffix on +// Windows. It is not an access check or a native executable format check. +const ( + FileExecutable FileState = "executable_file" + FileMissing FileState = "missing" + FileBrokenLink FileState = "broken_link" + FileNonregular FileState = "nonregular" + FileNonexecutable FileState = "nonexecutable" + FileInaccessible FileState = "inaccessible" + FileDeferred FileState = "inspection_deferred" +) + +type ExecutableCandidate struct { + Origin LookupOrigin `json:"sourceKind"` + LexicalPath string `json:"lexicalPath"` + ResolvedPath string `json:"resolvedPath,omitempty"` + // IsSymlink includes link traversal through parent directories. + IsSymlink bool `json:"isSymlink"` + State FileState `json:"fileState"` + Launcher bool `json:"indirectLauncher"` + Script bool `json:"script"` + // Platform identifies the observer, not an inspected binary architecture. + Platform string `json:"platform"` + ReasonCode string `json:"reasonCode,omitempty"` + Executed bool `json:"executed"` + // Identity is request-local evidence, intentionally not a serializable ID. + Identity *FileObservation `json:"-"` +} + +// FileObservation compares observed filesystem identity, not content integrity. +// Metadata reads are not atomic with later invocation. Reobserve before use; +// SameFile does not authorize execution, ownership, or deletion. +type FileObservation struct { + info fs.FileInfo +} + +func (o *FileObservation) SameFile(other *FileObservation) bool { + return o != nil && other != nil && os.SameFile(o.info, other.info) +} + +func (e LookupEnvironment) observe( + ctx context.Context, + path string, + origin LookupOrigin, +) (ExecutableCandidate, error) { + candidate := ExecutableCandidate{ + Origin: origin, LexicalPath: path, Platform: runtime.GOOS + "/" + runtime.GOARCH, + Launcher: e.indirectLauncher(path), Script: scriptPath(path), + } + observation, err := e.inspectFile(ctx, path) + if lookupCanceled(err) { + return ExecutableCandidate{}, err + } + candidate.IsSymlink = observation.symlink + if err != nil { + candidate.State = fileErrorState(err, candidate.IsSymlink) + if candidate.State == FileDeferred { + candidate.ReasonCode = LookupInspectionDeferred + } + return candidate, nil + } + candidate.ResolvedPath = observation.resolved + candidate.Script = candidate.Script || scriptPath(observation.resolved) + candidate.Launcher = candidate.Launcher || e.indirectLauncher(observation.resolved) + info := observation.info + candidate.recordFile(info) + return candidate, nil +} + +func (c *ExecutableCandidate) recordFile(info fs.FileInfo) { + c.State = observedFileState(c.LexicalPath, info) + // Windows observations already contain IDs captured from the open handle. + if !c.Launcher && info.Mode().IsRegular() && os.SameFile(info, info) { + c.Identity = &FileObservation{info: info} + } + if c.Launcher { + c.ReasonCode = LookupIndirectLauncher + } +} + +func fileErrorState(err error, symlink bool) FileState { + if errors.Is(err, errLookupDeferred) { + return FileDeferred + } + if errors.Is(err, fs.ErrNotExist) { + if symlink { + return FileBrokenLink + } + return FileMissing + } + return FileInaccessible +} + +func observedFileState(path string, info fs.FileInfo) FileState { + if !info.Mode().IsRegular() { + return FileNonregular + } + if !executableFile(path, info) { + return FileNonexecutable + } + return FileExecutable +} + +type lookupFile struct { + info fs.FileInfo + resolved string + symlink bool +} + +var errLookupDeferred = errors.New("passive filesystem inspection deferred by policy") + +func deferredCandidate(path string, origin LookupOrigin) ExecutableCandidate { + return ExecutableCandidate{ + Origin: origin, LexicalPath: path, Platform: runtime.GOOS + "/" + runtime.GOARCH, + State: FileDeferred, ReasonCode: LookupInspectionDeferred, Script: scriptPath(path), + } +} + +func lookupCanceled(err error) bool { + return errors.Is(err, context.Canceled) || errors.Is(err, context.DeadlineExceeded) +} diff --git a/pkg/dependencies/lookup_platform.go b/pkg/dependencies/lookup_platform.go new file mode 100644 index 0000000000..b5d1804de1 --- /dev/null +++ b/pkg/dependencies/lookup_platform.go @@ -0,0 +1,84 @@ +package dependencies + +import ( + "io/fs" + "path/filepath" + "runtime" + "slices" + "strings" +) + +const lookupWindows = "windows" + +func invocationPath(command string) bool { + if runtime.GOOS == lookupWindows { + return strings.ContainsAny(command, `:\/`) + } + return strings.ContainsRune(command, '/') +} + +func (e LookupEnvironment) executableNames(command string) []string { + if runtime.GOOS != lookupWindows { + return []string{command} + } + if filepath.Ext(command) != "" { + return []string{command} + } + var names []string + extensions, present := e.Value("PATHEXT") + if !present { + extensions = ".COM;.EXE;.BAT;.CMD" + } + for extension := range strings.SplitSeq(extensions, ";") { + if extension == "" || strings.ContainsAny(extension, `:\/`+"\x00") { + continue + } + if !strings.HasPrefix(extension, ".") { + extension = "." + extension + } + names = append(names, command+extension) + } + return names +} + +func executableFile(path string, info fs.FileInfo) bool { + if runtime.GOOS == lookupWindows { + // An extension is invocation evidence only, never proof of native format. + return filepath.Ext(path) != "" + } + return info.Mode().Perm()&0o111 != 0 +} + +func scriptPath(path string) bool { + return slices.Contains([]string{".cmd", ".bat", ".ps1"}, strings.ToLower(filepath.Ext(path))) +} + +func (e LookupEnvironment) indirectLauncher(path string) bool { + directory := filepath.Dir(path) + for key, child := range map[string]string{"MISE_DATA_DIR": "shims", "ASDF_DATA_DIR": "shims", "AQUA_ROOT_DIR": "bin"} { + if root, _ := e.Value( + key, + ); filepath.IsAbs(root) && + sameDirectory(directory, filepath.Join(root, child)) { + return true + } + } + // Only reviewed structural locations; no home discovery or directory scanning. + normalized := filepath.ToSlash(directory) + if runtime.GOOS == lookupWindows { + normalized = strings.ToLower(normalized) + } + for _, suffix := range []string{"/.local/share/mise/shims", "/.asdf/shims", "/.local/share/aquaproj-aqua/bin"} { + if strings.HasSuffix(normalized, suffix) { + return true + } + } + return false +} + +func sameDirectory(left, right string) bool { + if runtime.GOOS == lookupWindows { + return strings.EqualFold(left, right) + } + return left == right +} diff --git a/pkg/dependencies/lookup_safety.go b/pkg/dependencies/lookup_safety.go new file mode 100644 index 0000000000..dd2f013b21 --- /dev/null +++ b/pkg/dependencies/lookup_safety.go @@ -0,0 +1,171 @@ +package dependencies + +import ( + "context" + "io/fs" + "strings" +) + +// Each open is either a validated native disk root or a single child of a pinned +// handle. Implementations must open the reparse point itself and never follow it. +type windowsLookupMetadata interface { + driveTarget(drive string) (string, error) + open(parent uintptr, name string) (uintptr, error) + stat(handle uintptr) (info fs.FileInfo, reparse bool, err error) + close(handle uintptr) +} + +func inspectWindowsLookup( + ctx context.Context, + path string, + metadata windowsLookupMetadata, +) (lookupFile, error) { + if err := ctx.Err(); err != nil { + return lookupFile{}, err + } + drive, parts, valid := windowsLookupPath(path) + if !valid { + return lookupFile{}, errLookupDeferred + } + target, err := metadata.driveTarget(drive) + if canceled := ctx.Err(); canceled != nil { + return lookupFile{}, canceled + } + if err != nil || !localWindowsVolume(target) { + return lookupFile{}, errLookupDeferred + } + handle, err := openWindowsLookup(ctx, 0, target+`\`, metadata) + if err != nil { + return lookupFile{}, err + } + observed, err := walkWindowsLookup(ctx, handle, parts, metadata) + if err == nil { + observed.resolved = path + } + return observed, err +} + +func walkWindowsLookup( + ctx context.Context, + handle uintptr, + parts []string, + metadata windowsLookupMetadata, +) (lookupFile, error) { + defer func() { metadata.close(handle) }() + for { + info, reparse, err := statWindowsLookup(ctx, handle, metadata) + if err != nil { + return lookupFile{}, err + } + if reparse { + return lookupFile{symlink: true}, errLookupDeferred + } + if len(parts) == 0 { + return lookupFile{info: info}, nil + } + if !info.IsDir() { + return lookupFile{}, fs.ErrNotExist + } + next, err := openWindowsLookup(ctx, handle, parts[0], metadata) + if err != nil { + return lookupFile{}, err + } + metadata.close(handle) + handle, parts = next, parts[1:] + } +} + +func openWindowsLookup( + ctx context.Context, + parent uintptr, + name string, + metadata windowsLookupMetadata, +) (uintptr, error) { + if err := ctx.Err(); err != nil { + return 0, err + } + handle, err := metadata.open(parent, name) + if canceled := ctx.Err(); canceled != nil { + if err == nil { + metadata.close(handle) + } + return 0, canceled + } + return handle, err +} + +func statWindowsLookup( + ctx context.Context, + handle uintptr, + metadata windowsLookupMetadata, +) (fs.FileInfo, bool, error) { + if err := ctx.Err(); err != nil { + return nil, false, err + } + info, reparse, err := metadata.stat(handle) + if canceled := ctx.Err(); canceled != nil { + return nil, false, canceled + } + return info, reparse, err +} + +func windowsLookupPath(path string) (string, []string, bool) { + path = strings.ReplaceAll(path, "/", `\`) + if len(path) < 3 || path[1:3] != `:\` || !asciiDriveLetter(path[0]) { + return "", nil, false + } + var parts []string + for part := range strings.SplitSeq(path[3:], `\`) { + if part == "" { + continue + } + if !windowsLookupComponent(part) { + return "", nil, false + } + parts = append(parts, part) + } + return path[:2], parts, true +} + +func asciiDriveLetter(value byte) bool { + return value >= 'A' && value <= 'Z' || value >= 'a' && value <= 'z' +} + +func windowsLookupComponent(part string) bool { + if strings.HasSuffix(part, ".") || strings.HasSuffix(part, " ") || + strings.ContainsAny(part, ":<>\"|?*") { + return false + } + for _, value := range part { + if value < 32 { + return false + } + } + base, _, _ := strings.Cut(strings.ToUpper(part), ".") + base = strings.TrimRight(base, " ") + switch base { + case "CON", "PRN", "AUX", "NUL", "CONIN$", "CONOUT$": + return false + } + return !windowsNumberedDevice(base) +} + +func windowsNumberedDevice(base string) bool { + runes := []rune(base) + return len(runes) == 4 && (strings.HasPrefix(base, "COM") || strings.HasPrefix(base, "LPT")) && + strings.ContainsRune("123456789\u00b9\u00b2\u00b3", runes[3]) +} + +func localWindowsVolume(target string) bool { + const prefix = `\Device\HarddiskVolume` + number, found := strings.CutPrefix(target, prefix) + if !found || number == "" { + return false + } + for _, value := range number { + if value < '0' || value > '9' { + return false + } + } + return true +} diff --git a/pkg/dependencies/lookup_safety_test.go b/pkg/dependencies/lookup_safety_test.go new file mode 100644 index 0000000000..689c9a0a20 --- /dev/null +++ b/pkg/dependencies/lookup_safety_test.go @@ -0,0 +1,289 @@ +package dependencies + +import ( + "context" + "errors" + "fmt" + "io/fs" + "os" + "path/filepath" + "strings" + "testing" + "time" + + "github.com/stretchr/testify/require" +) + +const ( + lookupTestLocalVolume = `\Device\HarddiskVolume7` + lookupTestStatCall = "stat" + lookupTestReviewedLocation = "reviewed" +) + +// Synthetic boundary tests run on every host; they do not exercise Windows syscalls. +func TestWindowsLookupRejectsBeforeMetadata(t *testing.T) { + for _, path := range []string{ + `\\server\share\docker.exe`, `\\?\UNC\server\share\docker.exe`, + `\\.\pipe\docker`, `\\?\C:\docker.exe`, `\??\C:\docker.exe`, + `C:docker.exe`, `\docker.exe`, `C:\safe\..\docker.exe`, + `C:\safe\docker.exe:stream`, `C:\safe\NUL.exe`, + } { + t.Run(path, func(t *testing.T) { + metadata := &lookupMetadataSpy{t: t, forbidCalls: true} + observed, err := inspectWindowsLookup(context.Background(), path, metadata) + require.ErrorIs(t, err, errLookupDeferred) + require.Nil(t, observed.info) + require.Empty(t, metadata.calls) + }) + } +} + +func TestWindowsLookupRejectsMappedAndUnsupportedVolumesBeforeOpen(t *testing.T) { + for _, target := range []string{ + `\Device\Mup\server\share`, `\??\UNC\server\share`, `\??\C:\alias`, + `\Device\HarddiskVolume1\alias`, `\Device\CdRom0`, `\Device\HarddiskVolume`, + } { + metadata := &lookupMetadataSpy{t: t, target: target} + _, err := inspectWindowsLookup(context.Background(), `Z:\bin\docker.exe`, metadata) + require.ErrorIs(t, err, errLookupDeferred) + require.Equal(t, []string{"drive Z:"}, metadata.calls) + } +} + +func TestWindowsLookupStopsAtLocalParentReparse(t *testing.T) { + // The synthetic reparse represents a junction/link to a remote target. The + // boundary neither reads that target nor opens a child of the reparse handle. + for _, at := range []uintptr{1, 2, 3, 4} { + metadata := &lookupMetadataSpy{t: t, target: lookupTestLocalVolume, reparseAt: at} + observed, err := inspectWindowsLookup( + context.Background(), + `C:\safe\link\docker.exe`, + metadata, + ) + require.ErrorIs(t, err, errLookupDeferred) + require.True(t, observed.symlink) + require.Nil(t, observed.info) + require.Empty(t, observed.resolved) + require.Equal(t, at, metadata.opens) + require.Empty(t, metadata.live) + } +} + +func TestWindowsLookupLocalHandleWalk(t *testing.T) { + metadata := &lookupMetadataSpy{t: t, target: lookupTestLocalVolume} + path := `C:\safe\bin\docker.exe` + observed, err := inspectWindowsLookup(context.Background(), path, metadata) + require.NoError(t, err) + require.NotNil(t, observed.info) + require.Equal(t, path, observed.resolved) + require.False(t, observed.symlink) + require.Equal(t, uintptr(4), metadata.opens) + require.Empty(t, metadata.live) + require.Equal(t, []string{ + "drive C:", + `open \Device\HarddiskVolume7\`, + lookupTestStatCall, + "open safe", + lookupTestStatCall, + "open bin", + lookupTestStatCall, + "open docker.exe", + lookupTestStatCall, + }, metadata.calls) +} + +func TestWindowsLookupClosesHandlesOnFailure(t *testing.T) { + for _, failure := range []string{"open", lookupTestStatCall} { + metadata := &lookupMetadataSpy{t: t, target: lookupTestLocalVolume, failure: failure} + _, err := inspectWindowsLookup(context.Background(), `C:\safe\docker.exe`, metadata) + require.Error(t, err) + require.Empty(t, metadata.live) + } +} + +type lookupMetadataSpy struct { + t *testing.T + forbidCalls bool + target string + calls []string + opens uintptr + reparseAt uintptr + live map[uintptr]bool + failure string + afterCall func() +} + +func (s *lookupMetadataSpy) record(call string) { + s.t.Helper() + require.False(s.t, s.forbidCalls, "forbidden metadata call: %s", call) + s.calls = append(s.calls, call) + if s.afterCall != nil { + s.afterCall() + } +} + +func (s *lookupMetadataSpy) driveTarget(drive string) (string, error) { + s.record("drive " + drive) + return s.target, nil +} + +func (s *lookupMetadataSpy) open(parent uintptr, name string) (uintptr, error) { + s.record("open " + name) + if parent != 0 { + require.True(s.t, s.live[parent]) + require.NotEqual(s.t, s.reparseAt, parent, "must never traverse a reparse handle") + require.NotContains(s.t, name, `\`) + } + if s.failure == "open" { + return 0, errors.New("synthetic open failure") + } + if s.live == nil { + s.live = make(map[uintptr]bool) + } + s.opens++ + s.live[s.opens] = true + return s.opens, nil +} + +func (s *lookupMetadataSpy) stat(handle uintptr) (fs.FileInfo, bool, error) { + s.record(lookupTestStatCall) + require.True(s.t, s.live[handle]) + if s.failure == lookupTestStatCall { + return nil, false, errors.New("synthetic stat failure") + } + return lookupSyntheticInfo{name: "entry", directory: handle < 4}, handle == s.reparseAt, nil +} + +func (s *lookupMetadataSpy) close(handle uintptr) { + require.True(s.t, s.live[handle]) + delete(s.live, handle) +} + +type lookupSyntheticInfo struct { + name string + directory bool +} + +func (i lookupSyntheticInfo) Name() string { return i.name } +func (i lookupSyntheticInfo) Size() int64 { return 0 } +func (i lookupSyntheticInfo) Mode() fs.FileMode { + if i.directory { + return fs.ModeDir | 0o700 + } + return 0o700 +} +func (i lookupSyntheticInfo) ModTime() time.Time { return time.Time{} } +func (i lookupSyntheticInfo) IsDir() bool { return i.directory } +func (i lookupSyntheticInfo) Sys() any { return nil } + +func TestWindowsLookupComponentPolicy(t *testing.T) { + for _, part := range []string{".", "..", "COM1.exe", "LPT9", "trailing ", "trailing.", "bad\x00name"} { + require.False(t, windowsLookupComponent(part), part) + } + for _, part := range []string{" spaced dir", "docker tool.exe", "snow-\u96ea.exe", "COM10.exe"} { + require.True(t, windowsLookupComponent(part), part) + } + require.True(t, localWindowsVolume(`\Device\HarddiskVolume123`)) + require.False(t, localWindowsVolume(strings.Repeat("x", 30))) +} + +func TestLookupCancellationDuringPATHPreflight(t *testing.T) { + for _, explicit := range []bool{false, true} { + for _, cancelAt := range []int{1, 2} { + t.Run(fmt.Sprintf("explicit=%t/cancelAt=%d", explicit, cancelAt), func(t *testing.T) { + root := t.TempDir() + paths := []string{root} + if cancelAt == 2 { + paths = []string{filepath.Join(root, "first"), filepath.Join(root, "second")} + for _, path := range paths { + require.NoError(t, os.Mkdir(path, 0o700)) + } + } + environment, err := NewLookupEnvironment(map[string]string{ + "PATH": strings.Join(paths, string(filepath.ListSeparator)), + }, root) + require.NoError(t, err) + ctx, cancel := context.WithCancel(context.Background()) + defer cancel() + var reads []string + environment.inspect = func(ctx context.Context, path string) (lookupFile, error) { + reads = append(reads, path) + observed, inspectErr := inspectLookupFile(ctx, path) + if len(reads) == cancelAt { + cancel() + } + return observed, inspectErr + } + result, err := environment.LookupExecutable( + ctx, + LookupRequest{Command: toolDocker, Explicit: explicit}, + ) + require.Equal(t, context.Canceled, err) + require.Empty(t, result) + require.Len(t, reads, cancelAt, "no metadata read after cancellation") + }) + } + } +} + +func TestWindowsLookupCancellationAtMetadataBoundaries(t *testing.T) { + for cancelAt := 1; cancelAt <= 9; cancelAt++ { + t.Run(fmt.Sprint(cancelAt), func(t *testing.T) { + ctx, cancel := context.WithCancel(context.Background()) + defer cancel() + metadata := &lookupMetadataSpy{t: t, target: lookupTestLocalVolume} + metadata.afterCall = func() { + if len(metadata.calls) == cancelAt { + cancel() + } + } + observed, err := inspectWindowsLookup(ctx, `C:\safe\bin\docker.exe`, metadata) + require.Equal(t, context.Canceled, err) + require.Empty(t, observed) + require.Len(t, metadata.calls, cancelAt, "no metadata operation after cancellation") + require.Empty(t, metadata.live, "all acquired handles closed") + }) + } +} + +func TestLookupPreservesCancellationErrors(t *testing.T) { + root := t.TempDir() + bin := filepath.Join(root, "bin") + require.NoError(t, os.Mkdir(bin, 0o700)) + for _, failure := range []error{context.Canceled, context.DeadlineExceeded} { + for _, scenario := range []struct { + name string + at int + request LookupRequest + }{ + {name: "cwd", at: 1, request: LookupRequest{Command: toolDocker}}, + {name: "directory", at: 2, request: LookupRequest{Command: toolDocker}}, + {name: "candidate", at: 3, request: LookupRequest{Command: toolDocker}}, + {name: "explicit", at: 1, request: LookupRequest{Command: filepath.Join(bin, "docker.exe"), Explicit: true}}, + {name: lookupTestReviewedLocation, at: 1, request: LookupRequest{ + Command: toolDocker, ReviewedLocations: []string{filepath.Join(bin, "docker.exe")}, + }}, + } { + t.Run(failure.Error()+"/"+scenario.name, func(t *testing.T) { + values := map[string]string{"PATH": bin} + if scenario.name == lookupTestReviewedLocation { + values = nil + } + environment, err := NewLookupEnvironment(values, root) + require.NoError(t, err) + reads := 0 + environment.inspect = func(ctx context.Context, path string) (lookupFile, error) { + reads++ + if reads == scenario.at { + return lookupFile{}, failure + } + return inspectLookupFile(ctx, path) + } + result, err := environment.LookupExecutable(context.Background(), scenario.request) + require.Equal(t, failure, err) + require.Empty(t, result) + require.Equal(t, scenario.at, reads) + }) + } + } +} diff --git a/pkg/dependencies/lookup_safety_unix.go b/pkg/dependencies/lookup_safety_unix.go new file mode 100644 index 0000000000..3b9b496072 --- /dev/null +++ b/pkg/dependencies/lookup_safety_unix.go @@ -0,0 +1,120 @@ +//go:build !windows + +package dependencies + +import ( + "context" + "os" + "path/filepath" + "strings" + "syscall" +) + +func inspectLookupFile(ctx context.Context, path string) (lookupFile, error) { + if err := ctx.Err(); err != nil { + return lookupFile{}, err + } + info, err := os.Lstat(path) + if canceled := ctx.Err(); canceled != nil { + return lookupFile{}, canceled + } + if err != nil { + return lookupFile{}, err + } + observation := lookupFile{symlink: info.Mode()&os.ModeSymlink != 0} + resolved, err := resolveLookupPath(ctx, path) + if err != nil { + return observation, err + } + observation.symlink = observation.symlink || resolved != filepath.Clean(path) + observation.resolved = resolved + if err := ctx.Err(); err != nil { + return lookupFile{}, err + } + observation.info, err = os.Stat(resolved) + if canceled := ctx.Err(); canceled != nil { + return lookupFile{}, canceled + } + return observation, err +} + +// Resolve absolute Unix paths component by component so cancellation is checked +// between metadata calls, including link reads. In-flight syscalls cannot be interrupted. +func resolveLookupPath(ctx context.Context, path string) (string, error) { + walk := unixLookupPath{resolved: "/", pending: path} + for walk.pending != "" { + part, more := walk.nextComponent() + if part == "" { + continue + } + next := filepath.Join(walk.resolved, part) + info, target, err := lookupPathComponent(ctx, next) + if err != nil { + return "", err + } + if info.Mode()&os.ModeSymlink != 0 { + if err := walk.followLink(next, target, more); err != nil { + return "", err + } + continue + } + if more && !info.IsDir() { + return "", &os.PathError{Op: "lstat", Path: next, Err: syscall.ENOTDIR} + } + walk.resolved = next + } + return walk.resolved, ctx.Err() +} + +type unixLookupPath struct { + resolved string + pending string + links int +} + +func (w *unixLookupPath) nextComponent() (string, bool) { + part, rest, more := strings.Cut(w.pending, "/") + w.pending = rest + switch part { + case "", ".": + return "", more + case "..": + w.resolved = filepath.Dir(w.resolved) + return "", more + default: + return part, more + } +} + +func (w *unixLookupPath) followLink(path, target string, more bool) error { + w.links++ + if w.links > 255 { + return &os.PathError{Op: "readlink", Path: path, Err: syscall.ELOOP} + } + if more { + target += "/" + w.pending + } + w.pending = target + if filepath.IsAbs(target) { + w.resolved = "/" + } + return nil +} + +func lookupPathComponent(ctx context.Context, path string) (os.FileInfo, string, error) { + if err := ctx.Err(); err != nil { + return nil, "", err + } + info, err := os.Lstat(path) + if canceled := ctx.Err(); canceled != nil { + return nil, "", canceled + } + if err != nil || info.Mode()&os.ModeSymlink == 0 { + return info, "", err + } + target, err := os.Readlink(path) + if canceled := ctx.Err(); canceled != nil { + return nil, "", canceled + } + return info, target, err +} diff --git a/pkg/dependencies/lookup_safety_unix_test.go b/pkg/dependencies/lookup_safety_unix_test.go new file mode 100644 index 0000000000..a03aaf40b6 --- /dev/null +++ b/pkg/dependencies/lookup_safety_unix_test.go @@ -0,0 +1,50 @@ +//go:build !windows + +package dependencies + +import ( + "context" + "os" + "path/filepath" + "testing" + "time" + + "github.com/stretchr/testify/require" +) + +func TestLookupUnixResolutionPreservesTraversal(t *testing.T) { + root := t.TempDir() + require.NoError(t, os.MkdirAll(filepath.Join(root, "other", "child"), 0o700)) + require.NoError(t, os.WriteFile(filepath.Join(root, "other", "docker"), nil, 0o600)) + for name, target := range map[string]string{ + "relative": "other/child", "absolute": filepath.Join(root, "other", "child"), + "chain": "relative", "broken": "absent", "loop": "loop", + } { + require.NoError(t, os.Symlink(target, filepath.Join(root, name))) + } + for _, suffix := range []string{ + "/relative/../docker", "/absolute/../docker", "/chain/../docker", + "/other/./child/..//docker", "/other/docker/", "/other/docker/..", + "/broken", "/loop", "/relative/../../..", "/absolute/.", + } { + t.Run(suffix, func(t *testing.T) { + path := root + suffix + want, wantErr := filepath.EvalSymlinks(path) + got, err := resolveLookupPath(context.Background(), path) + if wantErr != nil { + require.Error(t, err) + return + } + require.NoError(t, err) + require.Equal(t, want, got) + }) + } +} + +func TestLookupUnixCanceledBeforeMetadata(t *testing.T) { + ctx, cancel := context.WithDeadline(context.Background(), time.Unix(1, 0)) + defer cancel() + observed, err := inspectLookupFile(ctx, filepath.Join(t.TempDir(), "missing")) + require.Equal(t, context.DeadlineExceeded, err) + require.Empty(t, observed) +} diff --git a/pkg/dependencies/lookup_safety_windows.go b/pkg/dependencies/lookup_safety_windows.go new file mode 100644 index 0000000000..3d207ab773 --- /dev/null +++ b/pkg/dependencies/lookup_safety_windows.go @@ -0,0 +1,92 @@ +package dependencies + +import ( + "context" + "errors" + "io/fs" + "os" + "syscall" + "unsafe" + + "golang.org/x/sys/windows" +) + +func inspectLookupFile(ctx context.Context, path string) (lookupFile, error) { + metadata := &nativeWindowsLookup{files: make(map[uintptr]*os.File)} + return inspectWindowsLookup(ctx, path, metadata) +} + +type nativeWindowsLookup struct { + files map[uintptr]*os.File +} + +func (*nativeWindowsLookup) driveTarget(drive string) (string, error) { + name, err := windows.UTF16PtrFromString(drive) + if err != nil { + return "", err + } + // Query the DOS-device namespace without opening the mapped filesystem. + const bufferSize = 32768 + buffer := make([]uint16, bufferSize) + _, err = windows.QueryDosDevice(name, &buffer[0], bufferSize) + return windows.UTF16ToString(buffer), err +} + +func (m *nativeWindowsLookup) open(parent uintptr, name string) (uintptr, error) { + objectName, err := windows.NewNTUnicodeString(name) + if err != nil { + return 0, err + } + attributes := windows.OBJECT_ATTRIBUTES{ + RootDirectory: windows.Handle(parent), ObjectName: objectName, + Attributes: windows.OBJ_CASE_INSENSITIVE, + } + attributes.Length = uint32(unsafe.Sizeof(attributes)) + var handle windows.Handle + // FILE_OPEN_REPARSE_POINT protects only the last component. The caller + // supplies one child at a time, anchored to a previously inspected handle. + err = windows.NtCreateFile( + &handle, + windows.FILE_READ_ATTRIBUTES|windows.SYNCHRONIZE, + &attributes, + &windows.IO_STATUS_BLOCK{}, + nil, + 0, + windows.FILE_SHARE_READ|windows.FILE_SHARE_WRITE|windows.FILE_SHARE_DELETE, + windows.FILE_OPEN, + windows.FILE_OPEN_REPARSE_POINT|windows.FILE_OPEN_NO_RECALL|windows.FILE_SYNCHRONOUS_IO_NONALERT, + 0, + 0, + ) + if err != nil { + if status, ok := errors.AsType[windows.NTStatus](err); ok { + err = status.Errno() + } + if !errors.Is(err, fs.ErrNotExist) && !errors.Is(err, fs.ErrPermission) { + err = errors.Join(errLookupDeferred, err) + } + return 0, err + } + key := uintptr(handle) + m.files[key] = os.NewFile(key, name) + return key, nil +} + +func (m *nativeWindowsLookup) stat(handle uintptr) (fs.FileInfo, bool, error) { + // File.Stat captures identity from this handle; os.SameFile will not reopen + // a lexical path later. No path-based Lstat, Stat, EvalSymlinks or Readlink. + info, err := m.files[handle].Stat() + if err != nil { + return nil, false, err + } + data, ok := info.Sys().(*syscall.Win32FileAttributeData) + if !ok { + return nil, false, errLookupDeferred + } + return info, data.FileAttributes&windows.FILE_ATTRIBUTE_REPARSE_POINT != 0, nil +} + +func (m *nativeWindowsLookup) close(handle uintptr) { + _ = m.files[handle].Close() + delete(m.files, handle) +} diff --git a/pkg/dependencies/lookup_safety_windows_test.go b/pkg/dependencies/lookup_safety_windows_test.go new file mode 100644 index 0000000000..e2e675b4d6 --- /dev/null +++ b/pkg/dependencies/lookup_safety_windows_test.go @@ -0,0 +1,129 @@ +package dependencies + +import ( + "context" + "os" + "path/filepath" + "strings" + "testing" + + "github.com/stretchr/testify/require" +) + +// Synthetic request-level tests on Windows use the production safety walk with +// injected metadata. No UNC or device path reaches a native filesystem call. +const lookupWindowsTestPATH = "PATH" + +type windowsUnsafeLookupCase struct { + name string + cwd string + path string + request LookupRequest +} + +func unsafeWindowsLookupCases(localCWD string) []windowsUnsafeLookupCase { + const ( + remote = `\\server\share` + safeCWD = `C:\safe` + ) + return []windowsUnsafeLookupCase{ + {name: "cwd", cwd: remote, path: `C:\bin`, request: LookupRequest{Command: toolDocker}}, + {name: "path", cwd: localCWD, path: remote, request: LookupRequest{Command: toolDocker}}, + {name: lookupTestReviewedLocation, cwd: safeCWD, request: LookupRequest{ + Command: toolDocker, ReviewedLocations: []string{remote + `\docker.exe`}, + }}, + {name: "explicit", cwd: safeCWD, request: LookupRequest{ + Command: remote + `\docker.exe`, Explicit: true, + }}, + {name: "relative", cwd: remote, request: LookupRequest{ + Command: `bin\docker.exe`, Explicit: true, + }}, + {name: "device", cwd: safeCWD, request: LookupRequest{ + Command: `\\.\pipe\docker.exe`, Explicit: true, + }}, + } +} + +func TestWindowsLookupUnsafeRequestLocations(t *testing.T) { + for _, scenario := range unsafeWindowsLookupCases(t.TempDir()) { + t.Run(scenario.name, func(t *testing.T) { + environment, err := NewLookupEnvironment(map[string]string{ + lookupWindowsTestPATH: scenario.path, + }, scenario.cwd) + require.NoError(t, err) + metadata := &lookupMetadataSpy{t: t, forbidCalls: true} + environment.inspect = func(ctx context.Context, path string) (lookupFile, error) { + if scenario.name == "path" && path == scenario.cwd { + return inspectLookupFile(ctx, path) + } + return inspectWindowsLookup(ctx, path, metadata) + } + result, err := environment.LookupExecutable(context.Background(), scenario.request) + require.NoError(t, err) + require.Equal(t, LookupInspectionDeferred, result.ReasonCode) + require.NotEmpty(t, result.Candidates) + for _, candidate := range result.Candidates { + require.Equal(t, FileDeferred, candidate.State) + require.Equal(t, LookupInspectionDeferred, candidate.ReasonCode) + require.Nil(t, candidate.Identity) + require.Empty(t, candidate.ResolvedPath) + } + require.Empty(t, metadata.calls) + }) + } +} + +func TestWindowsLookupNativeLocalIdentityAndReparseDeferral(t *testing.T) { + root := t.TempDir() + path := filepath.Join(root, "docker.exe") + require.NoError(t, os.WriteFile(path, []byte("fixture"), 0o600)) + environment, err := NewLookupEnvironment(nil, root) + require.NoError(t, err) + request := LookupRequest{Command: path, Explicit: true} + first, err := environment.LookupExecutable(context.Background(), request) + require.NoError(t, err) + require.Len(t, first.Candidates, 1) + require.Equal(t, FileExecutable, first.Candidates[0].State) + second, err := environment.LookupExecutable(context.Background(), request) + require.NoError(t, err) + require.True(t, first.Candidates[0].Identity.SameFile(second.Candidates[0].Identity)) + + link := filepath.Join(root, "local-link") + if err := os.Symlink(root, link); err != nil { + t.Skipf("native symlink creation unavailable; local identity passed: %v", err) + } + result, err := environment.LookupExecutable(context.Background(), LookupRequest{ + Command: filepath.Join(link, "docker.exe"), Explicit: true, + }) + require.NoError(t, err) + require.Equal(t, LookupInspectionDeferred, result.ReasonCode) + require.Len(t, result.Candidates, 1) + require.Equal(t, FileDeferred, result.Candidates[0].State) + require.True(t, result.Candidates[0].IsSymlink) + require.Nil(t, result.Candidates[0].Identity) + require.Empty(t, result.Candidates[0].ResolvedPath) +} + +func TestWindowsLookupNativePATHRejectsCWDCaseAlias(t *testing.T) { + root := t.TempDir() + fallback := filepath.Join(root, "bin") + require.NoError(t, os.Mkdir(fallback, 0o700)) + for _, directory := range []string{root, fallback} { + require.NoError( + t, + os.WriteFile(filepath.Join(directory, "docker.exe"), []byte("fixture"), 0o600), + ) + } + environment, err := NewLookupEnvironment(map[string]string{ + lookupWindowsTestPATH: strings.ToUpper(root) + ";" + fallback, "PATHEXT": ".EXE", + }, root) + require.NoError(t, err) + result, err := environment.LookupExecutable( + context.Background(), + LookupRequest{Command: toolDocker, Explicit: true}, + ) + require.NoError(t, err) + require.Len(t, result.Candidates, 1) + require.Equal(t, filepath.Join(fallback, "docker.EXE"), result.Candidates[0].LexicalPath) + require.Equal(t, FileExecutable, result.Candidates[0].State) +} diff --git a/pkg/dependencies/lookup_test.go b/pkg/dependencies/lookup_test.go new file mode 100644 index 0000000000..8ad8222837 --- /dev/null +++ b/pkg/dependencies/lookup_test.go @@ -0,0 +1,482 @@ +package dependencies_test + +import ( + "context" + "encoding/json" + "os" + "path/filepath" + "runtime" + "strings" + "testing" + + "github.com/devsy-org/devsy/internal/dependencytest" + "github.com/devsy-org/devsy/pkg/dependencies" + "github.com/stretchr/testify/suite" +) + +const ( + lookupTestExtension = ".exe" + lookupTestPATH = "PATH" +) + +type lookupSuite struct { + suite.Suite + root string +} + +func TestLookup(t *testing.T) { suite.Run(t, new(lookupSuite)) } + +func (s *lookupSuite) SetupTest() { + s.root = s.T().TempDir() +} + +func (s *lookupSuite) TestSnapshotPATHAndPassiveGuards() { + selected := s.executable("supplied/docker") + s.executable("ambient/docker") + s.executable(providerDocker) + s.executable("relative/docker") + separator := string(filepath.ListSeparator) + values := map[string]string{ + lookupTestPATH: separator + "." + separator + "relative" + separator + s.root + separator + filepath.Dir( + selected, + ) + separator, + "DOCKER_HOST": "", + "DOCKER_TLS_VERIFY": "", + "UNRELATED": "original", + } + s.T().Setenv(lookupTestPATH, filepath.Join(s.root, "ambient")) + environment := s.environment(values) + values[lookupTestPATH] = filepath.Join(s.root, "ambient") + delete(values, "DOCKER_HOST") + values["UNRELATED"] = "changed" + cwd, err := os.Getwd() + s.Require().NoError(err) + dependencytest.Preserve(s.T(), s.root) + result := s.lookup(environment, dependencies.LookupRequest{Command: providerDocker}) + s.Require().Len(result.Candidates, 1) + s.Equal(selected, result.Candidates[0].LexicalPath) + s.Equal(dependencies.LookupPATH, result.Candidates[0].Origin) + s.Equal(dependencies.FileExecutable, result.Candidates[0].State) + s.Empty(result.ReasonCode) + value, present := environment.Value("DOCKER_HOST") + s.True(present) + s.Empty(value) + value, present = environment.Value("UNRELATED") + s.True(present) + s.Equal("original", value) + _, present = environment.Value("ABSENT") + s.False(present) + after, err := os.Getwd() + s.Require().NoError(err) + s.Equal(cwd, after) + s.NoFileExists(filepath.Join(s.root, "EXECUTED")) +} + +func (s *lookupSuite) TestAbsentAndEmptyPATHNeverUseAmbientOrCWD() { + s.executable(providerDocker) + ambient := s.executable("ambient/docker") + s.T().Setenv(lookupTestPATH, filepath.Dir(ambient)) + dependencytest.Preserve(s.T(), s.root) + for _, values := range []map[string]string{nil, {lookupTestPATH: ""}, {lookupTestPATH: "."}} { + result := s.lookup( + s.environment(values), + dependencies.LookupRequest{Command: providerDocker}, + ) + s.Empty(result.Candidates) + s.Equal(dependencies.LookupMissing, result.ReasonCode) + } +} + +func (s *lookupSuite) TestExplicitSameAsDefaultRetainsIntent() { + first := s.executable("first/docker") + s.executable("second/docker") + reviewed := s.executable("reviewed/docker") + environment := s.environment(map[string]string{ + lookupTestPATH: filepath.Dir( + first, + ) + string( + filepath.ListSeparator, + ) + filepath.Join( + s.root, + "second", + ), + }) + dependencytest.Preserve(s.T(), s.root) + result := s.lookup(environment, dependencies.LookupRequest{ + Command: providerDocker, Explicit: true, ReviewedLocations: []string{reviewed}, + }) + s.Require().Len(result.Candidates, 1) + s.Equal(first, result.Candidates[0].LexicalPath) + s.Equal(dependencies.LookupExplicit, result.Candidates[0].Origin) + environmentChoice := s.lookup(environment, dependencies.LookupRequest{ + Command: providerDocker, Explicit: true, ExplicitOrigin: dependencies.LookupExplicitEnv, + }) + s.Require().Len(environmentChoice.Candidates, 1) + s.Equal(dependencies.LookupExplicitEnv, environmentChoice.Candidates[0].Origin) +} + +func (s *lookupSuite) TestInvalidExplicitNeverFallsBack() { + fallback := s.executable("fallback/docker") + environment := s.environment(map[string]string{lookupTestPATH: filepath.Dir(fallback)}) + dependencytest.Preserve(s.T(), s.root) + for _, command := range []string{"", "missing", filepath.Join(s.root, "missing"), "bad\x00path"} { + result := s.lookup(environment, dependencies.LookupRequest{ + Command: command, Explicit: true, ReviewedLocations: []string{fallback}, + }) + s.Equal(dependencies.LookupInvalidPath, result.ReasonCode) + for _, candidate := range result.Candidates { + s.NotEqual(fallback, candidate.LexicalPath) + } + } +} + +func (s *lookupSuite) TestOrderedPATHThenReviewedAndDeduplication() { + first := s.executable("first/docker") + second := s.executable("second/docker") + reviewed := s.executable("reviewed/docker") + locations := []string{reviewed, first} + environment := s.environment(map[string]string{ + lookupTestPATH: strings.Join( + []string{filepath.Dir(first), filepath.Dir(second), filepath.Dir(first)}, + string(filepath.ListSeparator), + ), + }) + dependencytest.Preserve(s.T(), s.root) + request := dependencies.LookupRequest{Command: providerDocker, ReviewedLocations: locations} + result := s.lookup(environment, request) + s.Require().Len(result.Candidates, 3) + for index, expected := range []string{first, second, reviewed} { + s.Equal(expected, result.Candidates[index].LexicalPath) + } + s.Equal(dependencies.LookupReviewed, result.Candidates[2].Origin) + s.Equal(result, s.lookup(environment, request)) + locations[0] = filepath.Join(s.root, "missing") + s.Equal(reviewed, result.Candidates[2].LexicalPath) +} + +func (s *lookupSuite) TestExplicitRelativeAndExactSpacesUnicode() { + path := s.executable(" spaced \u96ea dir/docker tool ") + name, err := filepath.Rel(s.root, path) + s.Require().NoError(err) + dependencytest.Preserve(s.T(), s.root) + result := s.lookup( + s.environment(nil), + dependencies.LookupRequest{Command: name, Explicit: true}, + ) + s.Require().Len(result.Candidates, 1) + s.Equal(path, result.Candidates[0].LexicalPath) + s.Equal(dependencies.FileExecutable, result.Candidates[0].State) + s.Equal(s.root, s.environment(nil).WorkingDirectory()) +} + +func (s *lookupSuite) TestSymlinkRetargetAndFileIdentity() { + first := s.executable("versions/first") + second := s.executable("versions/second") + link := filepath.Join(s.root, "package-manager") + if runtime.GOOS == osWindows { + link += lookupTestExtension + } + s.symlink(first, link) + environment := s.environment(nil) + request := dependencies.LookupRequest{Command: link, Explicit: true} + before := s.lookup(environment, request).Candidates[0] + s.True(before.IsSymlink) + s.Equal(link, before.LexicalPath) + if runtime.GOOS == osWindows { + s.assertDeferred(before) + } else { + s.Equal(s.resolved(first), before.ResolvedPath) + } + direct := s.lookup(environment, dependencies.LookupRequest{Command: first, Explicit: true}).Candidates[0] + if runtime.GOOS == osWindows { + s.Equal(dependencies.FileExecutable, direct.State) + s.NotNil(direct.Identity) + } else { + s.True(before.Identity.SameFile(direct.Identity)) + } + s.Require().NoError(os.Remove(link)) + s.symlink(second, link) + after := s.lookup(environment, request).Candidates[0] + s.Equal(link, after.LexicalPath) + if runtime.GOOS == osWindows { + s.assertDeferred(after) + } else { + s.Equal(s.resolved(second), after.ResolvedPath) + s.False(before.Identity.SameFile(after.Identity)) + } + encoded, err := json.Marshal(after) + s.Require().NoError(err) + s.NotContains(string(encoded), "fileIdentity") + s.Require().NoError(os.Remove(link)) + s.symlink(filepath.Join(s.root, "absent"), link) + dependencytest.Preserve(s.T(), s.root) + broken := s.lookup(environment, request) + if runtime.GOOS == osWindows { + s.Equal(dependencies.LookupInspectionDeferred, broken.ReasonCode) + s.assertDeferred(broken.Candidates[0]) + } else { + s.Equal(dependencies.LookupInvalidPath, broken.ReasonCode) + s.Equal(dependencies.FileBrokenLink, broken.Candidates[0].State) + } + s.Nil(broken.Candidates[0].Identity) +} + +func (s *lookupSuite) TestDirectoryNonexecutableAndMissing() { + file := s.executable("not-executable") + s.Require().NoError(os.Chmod(file, 0o600)) + dependencytest.Preserve(s.T(), s.root) + environment := s.environment(nil) + directory := s.lookup(environment, dependencies.LookupRequest{Command: s.root, Explicit: true}) + s.Equal(dependencies.FileNonregular, directory.Candidates[0].State) + s.Equal(dependencies.LookupInvalidPath, directory.ReasonCode) + if runtime.GOOS != osWindows { + result := s.lookup(environment, dependencies.LookupRequest{Command: file, Explicit: true}) + s.Equal(dependencies.FileNonexecutable, result.Candidates[0].State) + s.Equal(dependencies.LookupInvalidPath, result.ReasonCode) + } + missing := s.lookup( + environment, + dependencies.LookupRequest{Command: filepath.Join(s.root, "absent"), Explicit: true}, + ) + s.Equal(dependencies.LookupInvalidPath, missing.ReasonCode) +} + +func (s *lookupSuite) TestKnownLaunchersHaveNoComparableTargetIdentity() { + for _, relative := range []string{ + "home/.local/share/mise/shims/msb", "home/.asdf/shims/msb", "home/.local/share/aquaproj-aqua/bin/msb", + } { + path := s.executable(relative) + environment := s.environment(map[string]string{lookupTestPATH: filepath.Dir(path)}) + result := s.lookup(environment, dependencies.LookupRequest{Command: "msb"}) + s.Require().Len(result.Candidates, 1) + s.True(result.Candidates[0].Launcher) + s.Nil(result.Candidates[0].Identity) + s.Equal(dependencies.LookupIndirectLauncher, result.ReasonCode) + s.Equal(dependencies.LookupPATH, result.Candidates[0].Origin) + } +} + +func (s *lookupSuite) TestConfiguredLauncherRootAndExplicitStopsAtLauncher() { + shim := s.executable("custom/shims/msb") + fallback := s.executable("fallback/msb") + environment := s.environment(map[string]string{ + "MISE_DATA_DIR": filepath.Join(s.root, "custom"), + lookupTestPATH: filepath.Dir( + shim, + ) + string( + filepath.ListSeparator, + ) + filepath.Dir( + fallback, + ), + }) + dependencytest.Preserve(s.T(), s.root) + result := s.lookup(environment, dependencies.LookupRequest{Command: "msb", Explicit: true}) + s.Require().Len(result.Candidates, 1) + s.Equal(shim, result.Candidates[0].LexicalPath) + s.Equal(dependencies.LookupIndirectLauncher, result.ReasonCode) +} + +func (s *lookupSuite) TestLiteralShellCharactersAndSymlinkParentTraversal() { + if runtime.GOOS == osWindows { + s.T().Skip("Unix path traversal and literal shell filename semantics") + } + path := s.executable("literal/$HOME-~-${VALUE}-$(touch EXECUTED)") + link := filepath.Join(s.root, "link") + s.Require().NoError(os.MkdirAll(filepath.Join(s.root, "actual", "child"), 0o700)) + s.symlink(filepath.Join(s.root, "actual", "child"), link) + target := s.executable("actual/docker") + s.executable(providerDocker) + dependencytest.Preserve(s.T(), s.root) + environment := s.environment(nil) + literal := s.lookup(environment, dependencies.LookupRequest{Command: path, Explicit: true}) + s.Equal(path, literal.Candidates[0].LexicalPath) + lexical := link + "/../docker" + traversal := s.lookup(environment, dependencies.LookupRequest{Command: lexical, Explicit: true}) + s.Equal(lexical, traversal.Candidates[0].LexicalPath) + s.Equal(s.resolved(target), traversal.Candidates[0].ResolvedPath) +} + +func (s *lookupSuite) TestPATHSymlinkDotDotPreservesTraversal() { + if runtime.GOOS == osWindows { + s.T().Skip("Unix symlink/.. traversal semantics") + } + s.Require().NoError(os.MkdirAll(filepath.Join(s.root, "other", "child"), 0o700)) + link := filepath.Join(s.root, "link") + s.symlink(filepath.Join(s.root, "other", "child"), link) + target := s.executable("other/docker") + fallback := s.executable("fallback/docker") + s.executable(providerDocker) + directory := link + "/.." + dependencytest.Preserve(s.T(), s.root) + result := s.lookup(s.environment(map[string]string{ + lookupTestPATH: directory + string(filepath.ListSeparator) + filepath.Dir(fallback), + }), dependencies.LookupRequest{Command: providerDocker, Explicit: true}) + s.Require().Len(result.Candidates, 1) + s.Equal(directory+"/docker", result.Candidates[0].LexicalPath) + s.Equal(s.resolved(target), result.Candidates[0].ResolvedPath) +} + +func (s *lookupSuite) TestPATHRejectsActualWorkingDirectoryAlias() { + if runtime.GOOS == osWindows { + s.T().Skip("Unix directory alias fixture; Windows reparse traversal is deferred") + } + alias := filepath.Join(s.T().TempDir(), "cwd-alias") + s.symlink(s.root, alias) + s.executable(providerDocker) + fallback := s.executable("fallback/docker") + dependencytest.Preserve(s.T(), s.root) + result := s.lookup(s.environment(map[string]string{ + lookupTestPATH: alias + string(filepath.ListSeparator) + filepath.Dir(fallback), + }), dependencies.LookupRequest{Command: providerDocker, Explicit: true}) + s.Require().Len(result.Candidates, 1) + s.Equal(fallback, result.Candidates[0].LexicalPath) +} + +func (s *lookupSuite) TestScriptSuffixIncludesResolvedTarget() { + for _, extension := range []string{".cmd", ".BAT", ".ps1"} { + target := filepath.Join(s.root, "wrapper"+extension) + s.Require().NoError(os.WriteFile(target, []byte("fixture"), 0o600)) + // #nosec G302 -- Executable mode is required for this passive lookup fixture. + s.Require().NoError(os.Chmod(target, 0o700)) + link := filepath.Join(s.root, "docker"+extension+".exe") + s.symlink(target, link) + result := s.lookup( + s.environment(nil), + dependencies.LookupRequest{Command: link, Explicit: true}, + ) + s.Require().Len(result.Candidates, 1) + if runtime.GOOS == osWindows { + s.assertDeferred(result.Candidates[0]) + } else { + s.True(result.Candidates[0].Script, extension) + s.Equal(dependencies.FileExecutable, result.Candidates[0].State) + } + } + dependencytest.Preserve(s.T(), s.root) +} + +func (s *lookupSuite) TestInaccessibleDirectory() { + if runtime.GOOS == osWindows || os.Getuid() == 0 { + s.T().Skip("requires native Unix permission enforcement for a non-root user") + } + path := s.executable("restricted/docker") + directory := filepath.Dir(path) + s.Require().NoError(os.Chmod(directory, 0)) + s.T().Cleanup(func() { + // #nosec G302 -- Restore traversal permissions on the private test directory. + s.Require().NoError(os.Chmod(directory, 0o700)) + }) + environment := s.environment(nil) + result := s.lookup(environment, dependencies.LookupRequest{Command: path, Explicit: true}) + s.Equal(dependencies.FileInaccessible, result.Candidates[0].State) + s.Equal(dependencies.LookupInvalidPath, result.ReasonCode) +} + +func (s *lookupSuite) TestAliasToLauncherDoesNotExposeTargetIdentity() { + shim := s.executable("home/.asdf/shims/msb") + alias := filepath.Join(s.root, "alias") + if runtime.GOOS == osWindows { + alias += lookupTestExtension + } + s.symlink(shim, alias) + dependencytest.Preserve(s.T(), s.root) + result := s.lookup( + s.environment(nil), + dependencies.LookupRequest{Command: alias, Explicit: true}, + ) + s.Require().Len(result.Candidates, 1) + if runtime.GOOS == osWindows { + s.assertDeferred(result.Candidates[0]) + s.Equal(dependencies.LookupInspectionDeferred, result.ReasonCode) + return + } + s.True(result.Candidates[0].Launcher) + s.Nil(result.Candidates[0].Identity) + s.Equal(dependencies.LookupIndirectLauncher, result.ReasonCode) +} + +func (s *lookupSuite) TestCancellationAndInvalidRequests() { + environment := s.environment(nil) + ctx, cancel := context.WithCancel(context.Background()) + cancel() + _, err := environment.LookupExecutable(ctx, dependencies.LookupRequest{Command: providerDocker}) + s.ErrorIs(err, context.Canceled) + _, err = dependencies.NewLookupEnvironment(nil, ".") + s.Error(err) + _, err = (dependencies.LookupEnvironment{}).LookupExecutable( + context.Background(), + dependencies.LookupRequest{Command: providerDocker}, + ) + s.Error(err) + _, err = environment.LookupExecutable( + context.Background(), + dependencies.LookupRequest{Command: "./docker"}, + ) + s.Error(err) + _, err = environment.LookupExecutable( + context.Background(), + dependencies.LookupRequest{ + Command: providerDocker, + ReviewedLocations: []string{"relative"}, + }, + ) + s.Error(err) +} + +func (s *lookupSuite) environment(values map[string]string) dependencies.LookupEnvironment { + environment, err := dependencies.NewLookupEnvironment(values, s.root) + s.Require().NoError(err) + return environment +} + +func (s *lookupSuite) executable(relative string) string { + path := filepath.Join(s.root, relative) + if runtime.GOOS == osWindows { + path += lookupTestExtension + } + s.Require().NoError(os.MkdirAll(filepath.Dir(path), 0o700)) + // Any accidental shell invocation leaves evidence inside the guarded tree. + marker := filepath.Join(s.root, "EXECUTED") + body := "#!/bin/sh\nprintf executed > '" + strings.ReplaceAll(marker, "'", "'\\''") + "'\n" + s.Require().NoError(os.WriteFile(path, []byte(body), 0o600)) + // #nosec G302 -- Executable mode is required for this passive lookup fixture. + s.Require().NoError(os.Chmod(path, 0o700)) + return path +} + +func (s *lookupSuite) lookup( + environment dependencies.LookupEnvironment, + request dependencies.LookupRequest, +) dependencies.LookupResult { + result, err := environment.LookupExecutable(context.Background(), request) + s.Require().NoError(err) + s.False(result.Executed) + for _, candidate := range result.Candidates { + s.False(candidate.Executed) + } + return result +} + +func (s *lookupSuite) symlink(target, link string) { + s.T().Helper() + if err := os.Symlink(target, link); err != nil { + if runtime.GOOS == osWindows { + s.T().Skipf("native symlink creation unavailable: %v", err) + } + s.Require().NoError(err) + } +} + +func (s *lookupSuite) resolved(path string) string { + resolved, err := filepath.EvalSymlinks(path) + s.Require().NoError(err) + return resolved +} + +func (s *lookupSuite) assertDeferred(candidate dependencies.ExecutableCandidate) { + s.Equal(dependencies.FileDeferred, candidate.State) + s.Equal(dependencies.LookupInspectionDeferred, candidate.ReasonCode) + s.Empty(candidate.ResolvedPath) + s.Nil(candidate.Identity) + s.False(candidate.Executed) +} diff --git a/pkg/dependencies/lookup_windows_test.go b/pkg/dependencies/lookup_windows_test.go new file mode 100644 index 0000000000..3976d8e9f0 --- /dev/null +++ b/pkg/dependencies/lookup_windows_test.go @@ -0,0 +1,98 @@ +package dependencies_test + +import ( + "context" + "os" + "path/filepath" + "testing" + + "github.com/devsy-org/devsy/internal/dependencytest" + "github.com/devsy-org/devsy/pkg/dependencies" + "github.com/stretchr/testify/require" +) + +// These tests exercise the native Windows filesystem only when run on Windows. +func TestLookupWindowsPATHAndExtensions(t *testing.T) { + root := t.TempDir() + bin := filepath.Join(root, "bin") + require.NoError(t, os.Mkdir(bin, 0o700)) + for _, name := range []string{"Docker.CMD", "docker.EXE", "docker.PS1", "docker.BAT"} { + body := "@echo EXECUTED > \"" + filepath.Join(root, "EXECUTED") + "\"\r\nexit 99\r\n" + require.NoError(t, os.WriteFile(filepath.Join(bin, name), []byte(body), 0o600)) + } + dependencytest.Preserve(t, root) + environment, err := dependencies.NewLookupEnvironment(map[string]string{ + "Path": bin, "PathExt": ".CMD;.EXE;.PS1;.BAT", + }, root) + require.NoError(t, err) + result, err := environment.LookupExecutable( + context.Background(), + dependencies.LookupRequest{Command: "DOCKER"}, + ) + require.NoError(t, err) + require.Len(t, result.Candidates, 4) + require.True(t, result.Candidates[0].Script) + require.False(t, result.Candidates[1].Script) + require.True(t, result.Candidates[2].Script) + require.True(t, result.Candidates[3].Script) + require.False(t, result.Executed) + explicit, err := environment.LookupExecutable(context.Background(), dependencies.LookupRequest{ + Command: filepath.Join("bin", "docker"), Explicit: true, + }) + require.NoError(t, err) + require.Empty(t, explicit.ReasonCode) + require.True(t, explicit.Candidates[len(explicit.Candidates)-1].Script) +} + +func TestLookupWindowsEmptyPATHEXTAndAmbiguousEnvironment(t *testing.T) { + root := t.TempDir() + bin := filepath.Join(root, "bin") + require.NoError(t, os.Mkdir(bin, 0o700)) + require.NoError(t, os.WriteFile(filepath.Join(bin, "docker.exe"), []byte("fixture"), 0o600)) + environment, err := dependencies.NewLookupEnvironment( + map[string]string{"PATH": bin, "PATHEXT": ""}, + root, + ) + require.NoError(t, err) + result, err := environment.LookupExecutable( + context.Background(), + dependencies.LookupRequest{Command: "docker"}, + ) + require.NoError(t, err) + require.Equal(t, dependencies.LookupMissing, result.ReasonCode) + result, err = environment.LookupExecutable(context.Background(), dependencies.LookupRequest{ + Command: filepath.Join(bin, "docker.exe"), Explicit: true, + }) + require.NoError(t, err) + require.Empty(t, result.ReasonCode) + _, err = dependencies.NewLookupEnvironment(map[string]string{"Path": bin, "PATH": bin}, root) + require.Error(t, err) + for _, path := range []string{`C:docker.exe`, `\docker.exe`, `/docker.exe`, `/mnt/c/docker`, `C:\missing\docker.exe`} { + result, err = environment.LookupExecutable( + context.Background(), + dependencies.LookupRequest{Command: path, Explicit: true}, + ) + require.NoError(t, err) + require.Equal(t, dependencies.LookupInvalidPath, result.ReasonCode) + } +} + +func TestLookupWindowsExplicitSuffixNeverFallsBack(t *testing.T) { + root := t.TempDir() + path := filepath.Join(root, "missing.exe") + require.NoError(t, os.WriteFile(path+".CMD", []byte("exit 99\r\n"), 0o600)) + dependencytest.Preserve(t, root) + environment, err := dependencies.NewLookupEnvironment( + map[string]string{"PATHEXT": ".CMD"}, + root, + ) + require.NoError(t, err) + result, err := environment.LookupExecutable( + context.Background(), + dependencies.LookupRequest{Command: path, Explicit: true}, + ) + require.NoError(t, err) + require.Equal(t, dependencies.LookupInvalidPath, result.ReasonCode) + require.Len(t, result.Candidates, 1) + require.Equal(t, dependencies.FileMissing, result.Candidates[0].State) +} diff --git a/pkg/dependencies/metadata_codec.go b/pkg/dependencies/metadata_codec.go new file mode 100644 index 0000000000..8d895e645c --- /dev/null +++ b/pkg/dependencies/metadata_codec.go @@ -0,0 +1,211 @@ +package dependencies + +import ( + "bytes" + "encoding/json" + "errors" + "fmt" + "io" + "strings" + "time" +) + +const ( + MetadataSchemaVersion = 1 + maxMetadataBytes = 1 << 20 + maxMetadataReferences = 1024 +) + +// UnsupportedMetadataSchemaError permits read-only version inspection. No +// partially decoded document is returned, and writers must preserve the source. +type UnsupportedMetadataSchemaError struct{ Version int } + +func (e *UnsupportedMetadataSchemaError) Error() string { + return fmt.Sprintf( + "dependency metadata schema %d is unsupported; read-only inspection only", + e.Version, + ) +} + +func EncodeReceipt(receipt Receipt) ([]byte, error) { + return encodeMetadata(receipt.SchemaVersion, receipt) +} + +func DecodeReceipt(reader io.Reader) (Receipt, error) { + var receipt Receipt + err := decodeMetadata(reader, &receipt) + if err != nil { + return Receipt{}, err + } + return receipt, nil +} + +func EncodeRegistry(registry Registry) ([]byte, error) { + return encodeMetadata(registry.SchemaVersion, registry) +} + +func DecodeRegistry(reader io.Reader) (Registry, error) { + var registry Registry + err := decodeMetadata(reader, ®istry) + if err != nil { + return Registry{}, err + } + return registry, nil +} + +func EncodeJournal(journal Journal) ([]byte, error) { + return encodeMetadata(journal.SchemaVersion, journal) +} + +func DecodeJournal(reader io.Reader) (Journal, error) { + var journal Journal + err := decodeMetadata(reader, &journal) + if err != nil { + return Journal{}, err + } + return journal, nil +} + +func encodeMetadata(version int, document interface{ validate() error }) ([]byte, error) { + if err := validateMetadataVersion(version); err != nil { + return nil, err + } + if err := document.validate(); err != nil { + return nil, err + } + data, err := json.Marshal(document) + if err != nil { + return nil, fmt.Errorf("encode dependency metadata: %w", err) + } + if len(data)+1 > maxMetadataBytes { + return nil, errors.New("dependency metadata exceeds size limit") + } + return append(data, '\n'), nil +} + +func decodeMetadata(reader io.Reader, document interface{ validate() error }) error { + data, err := io.ReadAll(io.LimitReader(reader, maxMetadataBytes+1)) + if err != nil { + return fmt.Errorf("read dependency metadata: %w", err) + } + if len(data) > maxMetadataBytes { + return errors.New("dependency metadata exceeds size limit") + } + if err := inspectMetadata(data); err != nil { + return err + } + decoder := json.NewDecoder(bytes.NewReader(data)) + decoder.DisallowUnknownFields() + if err := decoder.Decode(document); err != nil { + return fmt.Errorf("decode dependency metadata: %w", err) + } + return document.validate() +} + +func inspectMetadata(data []byte) error { + var header map[string]json.RawMessage + if err := json.Unmarshal(data, &header); err != nil { + return errors.New("dependency metadata must be one JSON object") + } + var version int + if err := json.Unmarshal(header["schemaVersion"], &version); err != nil { + return errors.New("metadata schemaVersion is required") + } + if err := validateMetadataVersion(version); err != nil { + return err + } + decoder := json.NewDecoder(bytes.NewReader(data)) + if err := checkJSONValue(decoder); err != nil { + return fmt.Errorf("invalid dependency metadata: %w", err) + } + return metadataExactKeys(data) +} + +func validateMetadataVersion(version int) error { + if version > MetadataSchemaVersion { + return &UnsupportedMetadataSchemaError{Version: version} + } + if version != MetadataSchemaVersion { + return errors.New("invalid dependency metadata schema version") + } + return nil +} + +// encoding/json accepts case aliases for field names. Restrict the metadata +// vocabulary so aliases cannot silently overwrite a previously decoded field. +func metadataExactKeys(data []byte) error { + decoder := json.NewDecoder(bytes.NewReader(data)) + for { + token, err := decoder.Token() + if errors.Is(err, io.EOF) { + return nil + } + if err != nil { + return err + } + key, ok := metadataJSONKey(token, data[decoder.InputOffset():]) + if !ok { + continue + } + switch key { + case "schemaVersion", "identity", "recipeId", "recipeSha256", "sourceUrl", "installedAt", + "layout", "components", "validation", "toolId", "runtimeVersion", "platform", "archiveSha256", + "path", "type", "sha256", "size", "archive", "revision", "receipts", "operationId", "phase", + "artifacts", "startedAt", "updatedAt", "terminal", "at", "reasonCode": + default: + return errors.New("unknown dependency metadata field") + } + } +} + +func metadataID(value string) bool { + if len(value) == 0 || len(value) > 64 || reservedMetadataID(value) { + return false + } + return strings.IndexFunc(value, func(r rune) bool { + return !strings.ContainsRune("abcdefghijklmnopqrstuvwxyz0123456789-", r) + }) == -1 +} + +func metadataTime(value time.Time) bool { + return !value.IsZero() && value.Year() >= 1970 && value.Year() <= 9999 +} + +func reservedMetadataID(value string) bool { + switch value { + case "con", + "prn", + "aux", + "nul", + "com1", + "com2", + "com3", + "com4", + "com5", + "com6", + "com7", + "com8", + "com9", + "lpt1", + "lpt2", + "lpt3", + "lpt4", + "lpt5", + "lpt6", + "lpt7", + "lpt8", + "lpt9": + return true + default: + return false + } +} + +func metadataJSONKey(token json.Token, rest []byte) (string, bool) { + key, ok := token.(string) + if !ok { + return "", false + } + rest = bytes.TrimSpace(rest) + return key, len(rest) > 0 && rest[0] == ':' +} diff --git a/pkg/dependencies/metadata_codec_test.go b/pkg/dependencies/metadata_codec_test.go new file mode 100644 index 0000000000..4ef92ca8f4 --- /dev/null +++ b/pkg/dependencies/metadata_codec_test.go @@ -0,0 +1,358 @@ +package dependencies + +import ( + "bytes" + "encoding/json" + "errors" + "io" + "strings" + "testing" + "time" + + "github.com/stretchr/testify/require" + "github.com/stretchr/testify/suite" +) + +const ( + metadataInvalidLink = "symlink" + metadataTraversalPath = "../outside" +) + +type MetadataCodecSuite struct{ suite.Suite } + +func TestMetadataCodecs(t *testing.T) { suite.Run(t, new(MetadataCodecSuite)) } + +func metadataReceiptFixture() Receipt { + return Receipt{ + SchemaVersion: MetadataSchemaVersion, + Identity: ReceiptIdentity{ + ToolID: "microsandbox", + RuntimeVersion: "v0.7.7", + Platform: "linux/amd64", + ArchiveSHA256: strings.Repeat("a", 64), + }, + RecipeID: sourceRecordedCandidate().ID, + RecipeSHA256: strings.Repeat("b", 64), + SourceURL: "https://github.com/superradcompany/microsandbox/releases/download/" + + "v0.7.7/microsandbox-linux-x86_64.tar.gz", + InstalledAt: time.Date( + 2026, + 10, + 19, + 0, + 0, + 0, + 0, + time.UTC, + ), + Layout: "flat_verbatim_no_links", + Components: []ReceiptComponent{ + { + Path: metadataExecutable, + Type: metadataRegular, + SHA256: strings.Repeat("c", 64), + Size: 1024, + }, + { + Path: metadataFirmware, + Type: metadataRegular, + SHA256: strings.Repeat("d", 64), + Size: 4096, + }, + }, + Validation: ReceiptValidation{Archive: "sha256_verified", Layout: "validated"}, + } +} + +func metadataRegistryFixture() Registry { + return Registry{ + SchemaVersion: MetadataSchemaVersion, + Revision: 1, + Receipts: []ReceiptIdentity{metadataReceiptFixture().Identity}, + } +} + +func metadataJournalFixture() Journal { + receipt := metadataReceiptFixture() + return Journal{ + SchemaVersion: MetadataSchemaVersion, OperationID: "operation-123", Phase: PhasePlanned, + Artifacts: []ReceiptIdentity{receipt.Identity}, Receipts: []ReceiptIdentity{}, + StartedAt: receipt.InstalledAt, UpdatedAt: receipt.InstalledAt, + } +} + +func (s *MetadataCodecSuite) TestDeterministicRoundTrips() { + receipt := metadataReceiptFixture() + data, err := EncodeReceipt(receipt) + s.Require().NoError(err) + decoded, err := DecodeReceipt(bytes.NewReader(data)) + s.Require().NoError(err) + s.Equal(receipt, decoded) + again, err := EncodeReceipt(decoded) + s.Require().NoError(err) + s.Equal(data, again) + decoded.Components[0].Path = "mutated-component-path" + s.Equal(metadataExecutable, receipt.Components[0].Path) + registry := metadataRegistryFixture() + data, err = EncodeRegistry(registry) + s.Require().NoError(err) + decodedRegistry, err := DecodeRegistry(bytes.NewReader(data)) + s.Require().NoError(err) + s.Equal(registry, decodedRegistry) + again, err = EncodeRegistry(decodedRegistry) + s.Require().NoError(err) + s.Equal(data, again) + journal := metadataJournalFixture() + data, err = EncodeJournal(journal) + s.Require().NoError(err) + decodedJournal, err := DecodeJournal(bytes.NewReader(data)) + s.Require().NoError(err) + s.Equal(journal, decodedJournal) + again, err = EncodeJournal(decodedJournal) + s.Require().NoError(err) + s.Equal(data, again) +} + +func (s *MetadataCodecSuite) TestReceiptPreservesCatalogRecipeID() { + recipe := sourceRecordedCandidate() + s.Require().NoError(validateRecipe(recipe)) + s.Equal("microsandbox-0.7.7-linux-amd64", recipe.ID) + receipt := metadataReceiptFixture() + receipt.RecipeID = recipe.ID + s.Run("encode", func() { + data, err := EncodeReceipt(receipt) + s.Require().NoError(err) + decoded, err := DecodeReceipt(bytes.NewReader(data)) + s.Require().NoError(err) + s.Equal(receipt, decoded) + }) + s.Run("decode", func() { + data, err := json.Marshal(receipt) + s.Require().NoError(err) + decoded, err := DecodeReceipt(bytes.NewReader(data)) + s.Require().NoError(err) + s.Equal(receipt, decoded) + }) +} + +func (s *MetadataCodecSuite) TestReceiptRejectsMalformedRecipeIDs() { + for _, id := range []string{ + "", ".", "..", metadataTraversalPath, "a/b", `a\b`, "C:ads", "Upper", "a b", "a\nb", + } { + s.Run(id, func() { + recipe := sourceRecordedCandidate() + recipe.ID = id + s.Require().Error(validateRecipe(recipe)) + receipt := metadataReceiptFixture() + receipt.RecipeID = id + _, err := EncodeReceipt(receipt) + s.Error(err) + data, err := json.Marshal(receipt) + s.Require().NoError(err) + decoded, err := DecodeReceipt(bytes.NewReader(data)) + s.Error(err) + s.Equal(Receipt{}, decoded) + }) + } +} + +func (s *MetadataCodecSuite) TestMalformedDocuments() { + original, err := EncodeRegistry(metadataRegistryFixture()) + s.Require().NoError(err) + cases := []string{ + "null", + "[]", + "{}", + string(original) + " {}", + string(original) + "garbage", + strings.Replace( + string(original), + `"schemaVersion":1`, + `"schemaVersion":1,"schemaVersion":1`, + 1, + ), + strings.Replace(string(original), `"revision":1`, `"revision":1,"Revision":2`, 1), + strings.Replace(string(original), `"revision":1`, `"revision":1,"unknown":true`, 1), + strings.Replace(string(original), `"revision":1`, `"revision":null`, 1), + strings.Replace(string(original), `"revision":1`, `"revision":-1`, 1), + strings.Replace(string(original), `"revision":1`, `"revision":0`, 1), + strings.Replace(string(original), `"receipts":[`, `"receipts":null,"other":[`, 1), + strings.Replace( + string(original), + `"platform":"linux/amd64"`, + `"platform":"linux/amd64","platform":"linux/amd64"`, + 1, + ), + strings.Replace( + string(original), + `"platform":"linux/amd64"`, + `"platform":"linux/amd64","revision":1`, + 1, + ), + strings.Replace(string(original), `"schemaVersion":1`, `"schemaVersion":0`, 1), + } + for _, data := range cases { + s.Run(data[:min(len(data), 80)], func() { + decoded, err := DecodeRegistry(strings.NewReader(data)) + s.Error(err) + s.Equal(Registry{}, decoded) + }) + } +} + +func (s *MetadataCodecSuite) TestFutureSchemaInspection() { + for _, decode := range []func(io.Reader) error{ + func(r io.Reader) error { _, err := DecodeReceipt(r); return err }, + func(r io.Reader) error { _, err := DecodeRegistry(r); return err }, + func(r io.Reader) error { _, err := DecodeJournal(r); return err }, + } { + err := decode( + strings.NewReader( + `{"schemaVersion":27,"unknownFuture":{"value":true,"nullable":null}}`, + ), + ) + var future *UnsupportedMetadataSchemaError + s.Require().ErrorAs(err, &future) + s.Equal(27, future.Version) + s.Contains(err.Error(), "read-only") + } + receipt := metadataReceiptFixture() + receipt.SchemaVersion = 27 + _, err := EncodeReceipt(receipt) + var future *UnsupportedMetadataSchemaError + s.ErrorAs(err, &future) +} + +func (s *MetadataCodecSuite) TestReceiptRejectsUntrustedContent() { + cases := map[string]func(*Receipt){ + "archive digest": func(r *Receipt) { r.Identity.ArchiveSHA256 = "abcd" }, + "recipe digest": func(r *Receipt) { r.RecipeSHA256 = strings.Repeat("A", 64) }, + "file digest": func(r *Receipt) { r.Components[0].SHA256 = "bad" }, + "size": func(r *Receipt) { r.Components[0].Size = -1 }, + "link": func(r *Receipt) { r.Components[0].Type = metadataInvalidLink }, + "script": func(r *Receipt) { r.Components[0].Path = "install.sh" }, + "layout": func(r *Receipt) { r.Layout = "bin_lib" }, + "duplicate": func(r *Receipt) { r.Components[1] = r.Components[0] }, + "wrong platform": func(r *Receipt) { r.Identity.Platform = "windows/amd64" }, + "validation": func(r *Receipt) { r.Validation.Archive = "not_checked" }, + "userinfo": func(r *Receipt) { r.SourceURL = "https://user:password@github.com/release" }, + "encoded userinfo": func(r *Receipt) { r.SourceURL = "https://user%3Apassword@github.com/release" }, + "query token": func(r *Receipt) { r.SourceURL += "?token=secret" }, + "fragment": func(r *Receipt) { r.SourceURL += "#secret" }, + "http": func(r *Receipt) { r.SourceURL = strings.Replace(r.SourceURL, "https:", "http:", 1) }, + } + for name, change := range cases { + s.Run(name, func() { + receipt := metadataReceiptFixture() + change(&receipt) + _, err := EncodeReceipt(receipt) + s.Error(err) + data, err := json.Marshal(receipt) + s.Require().NoError(err) + _, err = DecodeReceipt(bytes.NewReader(data)) + s.Error(err) + }) + } + paths := []string{ + metadataTraversalPath, "/msb", "bin/msb", `C:\msb`, `\\server\msb`, "msb:stream", + "CON", "NUL", "msb.", "libkrunfw.so", "current", "./msb", + } + for _, path := range paths { + receipt := metadataReceiptFixture() + receipt.Components[0].Path = path + data, err := json.Marshal(receipt) + s.Require().NoError(err) + _, err = DecodeReceipt(bytes.NewReader(data)) + s.Error(err, path) + } +} + +func (s *MetadataCodecSuite) TestRegistryIdentityAndRevision() { + registry := metadataRegistryFixture() + other := registry.Receipts[0] + other.ArchiveSHA256 = strings.Repeat("e", 64) + registry.Receipts = append(registry.Receipts, other) + _, err := EncodeRegistry(registry) + s.NoError(err, "same version, distinct full digest is a distinct bundle") + registry.Receipts = append(registry.Receipts, other) + _, err = EncodeRegistry(registry) + s.Error(err) + registry = metadataRegistryFixture() + registry.Revision = 0 + _, err = EncodeRegistry(registry) + s.Error(err) + registry.Revision = 1 + registry.Receipts = []ReceiptIdentity{} + _, err = EncodeRegistry(registry) + s.NoError(err) +} + +func (s *MetadataCodecSuite) TestJournalPhasesAndTerminalData() { + phases := []JournalPhase{ + PhasePlanned, + PhaseDownloading, + PhaseVerifiedArchive, + PhaseExtracting, + PhasePublished, + PhaseBinding, + } + for _, phase := range phases { + journal := metadataJournalFixture() + journal.Phase = phase + _, err := EncodeJournal(journal) + s.NoError(err) + journal.Terminal = &JournalTerminal{At: journal.UpdatedAt, ReasonCode: "complete"} + _, err = EncodeJournal(journal) + s.Error(err) + } + reasons := map[JournalPhase]string{ + PhaseComplete: "complete", + PhaseCanceled: "canceled", + PhaseFailed: "dependency_integrity_failed", + PhaseInterrupted: "dependency_operation_interrupted", + } + for phase, reason := range reasons { + journal := metadataJournalFixture() + journal.Phase = phase + _, err := EncodeJournal(journal) + s.Error(err) + journal.Terminal = &JournalTerminal{At: journal.UpdatedAt, ReasonCode: reason} + data, err := EncodeJournal(journal) + s.Require().NoError(err) + decoded, err := DecodeJournal(bytes.NewReader(data)) + s.Require().NoError(err) + s.Equal(journal, decoded) + journal.Terminal.ReasonCode = "password=secret" + _, err = EncodeJournal(journal) + s.Error(err) + } + for _, id := range []string{ + "..", metadataTraversalPath, "C:ads", "con", "nul", "com1", "lpt9", "a/b", `a\b`, + sourceRecordedCandidate().ID, "operation_123", + } { + journal := metadataJournalFixture() + journal.OperationID = id + _, err := EncodeJournal(journal) + s.Error(err, id) + } +} + +type boundedMetadataReader struct{ remaining int } + +func (r *boundedMetadataReader) Read(data []byte) (int, error) { + if len(data) > r.remaining { + return 0, errors.New("reader consumed beyond metadata bound") + } + for i := range data { + data[i] = ' ' + } + r.remaining -= len(data) + return len(data), nil +} + +func TestMetadataReadBound(t *testing.T) { + reader := &boundedMetadataReader{remaining: maxMetadataBytes + 1} + _, err := DecodeRegistry(reader) + require.ErrorContains(t, err, "size limit") + require.Zero(t, reader.remaining) +} diff --git a/pkg/dependencies/metadata_write.go b/pkg/dependencies/metadata_write.go new file mode 100644 index 0000000000..760623077f --- /dev/null +++ b/pkg/dependencies/metadata_write.go @@ -0,0 +1,321 @@ +package dependencies + +import ( + "bytes" + "context" + "crypto/rand" + "errors" + "fmt" + "io" + "os" + "strings" +) + +// metadataWriter only replaces mutable metadata. Callers in later transaction +// work must hold the relevant locks through read/check/write; this is not CAS. +// The caller owns root, an explicitly allocated private state directory. +type metadataWriter struct { + root *os.Root + hooks metadataWriteHooks +} + +type metadataDestination struct { + root *os.Root + name string + journal bool +} + +// Hooks are per writer/operation, never process-global filesystem replacements. +type metadataWriteHooks struct { + write func(*os.File, []byte) (int, error) + sync func(*os.File) error + close func(*os.File) error + rename func(*os.Root, string, string) error + syncDir func(*os.Root) error +} + +// Published means replacement happened but durability was not established. A +// caller must inspect/reconcile under its locks, never assume rollback or retry. +type metadataCommitError struct { + Published bool + Err error +} + +func (e *metadataCommitError) Error() string { + return fmt.Sprintf("dependency metadata replacement published=%t: %v", e.Published, e.Err) +} + +func (e *metadataCommitError) Unwrap() error { return e.Err } + +func newMetadataWriter(root *os.Root) (*metadataWriter, error) { + if err := metadataWriteSupported(); err != nil { + return nil, err + } + if err := validateMetadataRoot(root); err != nil { + return nil, err + } + return &metadataWriter{root: root, hooks: metadataWriteHooks{ + write: (*os.File).Write, sync: (*os.File).Sync, close: (*os.File).Close, + rename: (*os.Root).Rename, syncDir: syncMetadataDirectory, + }}, nil +} + +func validateMetadataRoot(root *os.Root) error { + if root == nil { + return errors.New("private metadata root is required") + } + info, err := root.Stat(".") + if err != nil { + return err + } + if !info.IsDir() { + return errors.New("metadata root must be a directory") + } + return validatePrivateMetadata(info) +} + +// initialize is the only directory-creating path. Opening and reading metadata +// never initialize state. The supplied root itself must already exist. +func (w *metadataWriter) initialize(ctx context.Context) error { + if err := ctx.Err(); err != nil { + return err + } + if err := w.root.Mkdir("operations", 0o700); err != nil && !errors.Is(err, os.ErrExist) { + return err + } + operations, err := openMetadataOperations(w.root) + if err != nil { + return err + } + if err := operations.Close(); err != nil { + return err + } + if err := ctx.Err(); err != nil { + return err + } + return w.hooks.syncDir(w.root) +} + +func openMetadataOperations(root *os.Root) (*os.Root, error) { + before, err := root.Lstat("operations") + if err != nil { + return nil, err + } + if !before.IsDir() { + return nil, errors.New("metadata operations directory must not be a link") + } + child, err := root.OpenRoot("operations") + if err != nil { + return nil, err + } + after, err := child.Stat(".") + if err == nil && !os.SameFile(before, after) { + err = errors.New("metadata operations directory changed") + } + if err == nil { + err = validateMetadataRoot(child) + } + if err != nil { + return nil, errors.Join(err, child.Close()) + } + return child, nil +} + +func (w *metadataWriter) writeRegistry(ctx context.Context, registry Registry) error { + data, err := EncodeRegistry(registry) + if err != nil { + return err + } + return w.replace(ctx, metadataDestination{root: w.root, name: "registry.json"}, data) +} + +func (w *metadataWriter) writeJournal(ctx context.Context, journal Journal) (err error) { + if err := ctx.Err(); err != nil { + return err + } + data, err := EncodeJournal(journal) + if err != nil { + return err + } + operations, err := openMetadataOperations(w.root) + if err != nil { + return err + } + defer func() { err = errors.Join(err, operations.Close()) }() + return w.replace( + ctx, + metadataDestination{root: operations, name: journal.OperationID + ".json", journal: true}, + data, + ) +} + +type metadataTemporary struct { + name string + file *os.File + identity os.FileInfo +} + +func allocateMetadataTemp( + ctx context.Context, + destination metadataDestination, +) (*metadataTemporary, error) { + if err := destination.validate(); err != nil { + return nil, err + } + if err := ctx.Err(); err != nil { + return nil, err + } + if err := checkExistingMetadata(destination); err != nil { + return nil, err + } + if err := ctx.Err(); err != nil { + return nil, err + } + name := ".metadata-" + rand.Text() + ".tmp" + file, err := destination.root.OpenFile(name, os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0o600) + if err != nil { + return nil, err + } + identity, err := file.Stat() + if err != nil { + return nil, errors.Join(err, file.Close()) + } + return &metadataTemporary{name: name, file: file, identity: identity}, nil +} + +func (w *metadataWriter) replace( + ctx context.Context, + destination metadataDestination, + data []byte, +) (err error) { + temp, err := allocateMetadataTemp(ctx, destination) + if err != nil { + return err + } + published := false + defer func() { + _ = temp.file.Close() + if !published { + err = errors.Join(err, removeMetadataTemp(destination.root, temp.name, temp.identity)) + } + }() + if err := w.prepare(ctx, temp.file, data); err != nil { + return err + } + published, err = w.publish(ctx, destination, temp.name) + return err +} + +func (w *metadataWriter) publish( + ctx context.Context, + destination metadataDestination, + tempName string, +) (bool, error) { + if err := ctx.Err(); err != nil { + return false, err + } + if err := w.hooks.rename(destination.root, tempName, destination.name); err != nil { + return false, err + } + if err := ctx.Err(); err != nil { + return true, &metadataCommitError{Published: true, Err: err} + } + if err := w.hooks.syncDir(destination.root); err != nil { + return true, &metadataCommitError{Published: true, Err: err} + } + return true, nil +} + +func (w *metadataWriter) prepare(ctx context.Context, file *os.File, data []byte) error { + if err := ctx.Err(); err != nil { + return err + } + n, err := w.hooks.write(file, data) + if err != nil { + return err + } + if n != len(data) { + return io.ErrShortWrite + } + if err := ctx.Err(); err != nil { + return err + } + if err := w.hooks.sync(file); err != nil { + return err + } + if err := ctx.Err(); err != nil { + return err + } + return w.hooks.close(file) +} + +func removeMetadataTemp(root *os.Root, name string, created os.FileInfo) error { + current, err := root.Lstat(name) + if errors.Is(err, os.ErrNotExist) { + return nil + } + if err != nil { + return err + } + if !os.SameFile(created, current) { + return errors.New("metadata temporary file identity changed; left untouched") + } + return root.Remove(name) +} + +func checkExistingMetadata(destination metadataDestination) error { + data, err := readExistingMetadata(destination) + if err != nil || data == nil { + return err + } + // Replacement cannot silently repair corrupt or future documents. Recovery + // requires an explicit policy under the later transaction locks. + if !destination.journal { + _, err := DecodeRegistry(bytes.NewReader(data)) + return err + } + existing, err := DecodeJournal(bytes.NewReader(data)) + if err == nil && existing.OperationID+".json" != destination.name { + return errors.New("journal identity does not match metadata name") + } + return err +} + +func readExistingMetadata(destination metadataDestination) (data []byte, err error) { + file, err := openMetadataFile(destination.root, destination.name) + if errors.Is(err, os.ErrNotExist) { + return nil, nil + } + if err != nil { + return nil, err + } + defer func() { err = errors.Join(err, file.Close()) }() + info, err := file.Stat() + if err != nil { + return nil, err + } + if !info.Mode().IsRegular() { + return nil, errors.New("metadata destination must be a regular file") + } + if err := validatePrivateMetadata(info); err != nil { + return nil, err + } + data, err = io.ReadAll(io.LimitReader(file, maxMetadataBytes+1)) + if len(data) > maxMetadataBytes { + return nil, errors.New("existing dependency metadata exceeds size limit") + } + return data, err +} + +func (d metadataDestination) validate() error { + if !d.journal { + if d.name != "registry.json" { + return errors.New("unrecognized registry metadata name") + } + return nil + } + if !strings.HasSuffix(d.name, ".json") || !metadataID(strings.TrimSuffix(d.name, ".json")) { + return errors.New("invalid operation metadata name") + } + return nil +} diff --git a/pkg/dependencies/metadata_write_unix.go b/pkg/dependencies/metadata_write_unix.go new file mode 100644 index 0000000000..ec986a6f9d --- /dev/null +++ b/pkg/dependencies/metadata_write_unix.go @@ -0,0 +1,33 @@ +//go:build linux || darwin + +package dependencies + +import ( + "errors" + "os" + "syscall" +) + +func metadataWriteSupported() error { return nil } + +func validatePrivateMetadata(info os.FileInfo) error { + stat, ok := info.Sys().(*syscall.Stat_t) + if !ok || int64(stat.Uid) != int64(os.Geteuid()) || info.Mode().Perm()&0o077 != 0 { + return errors.New("metadata must be private to the current user") + } + return nil +} + +func openMetadataFile(root *os.Root, name string) (*os.File, error) { + // NONBLOCK avoids a substituted FIFO hanging a metadata read; NOFOLLOW refuses + // destination links, including links whose targets are still inside the root. + return root.OpenFile(name, os.O_RDONLY|syscall.O_NOFOLLOW|syscall.O_NONBLOCK, 0) +} + +func syncMetadataDirectory(root *os.Root) error { + directory, err := root.Open(".") + if err != nil { + return err + } + return errors.Join(directory.Sync(), directory.Close()) +} diff --git a/pkg/dependencies/metadata_write_unix_test.go b/pkg/dependencies/metadata_write_unix_test.go new file mode 100644 index 0000000000..27c97852e5 --- /dev/null +++ b/pkg/dependencies/metadata_write_unix_test.go @@ -0,0 +1,341 @@ +//go:build linux || darwin + +package dependencies + +import ( + "bytes" + "context" + "errors" + "io" + "os" + "path/filepath" + "strings" + "sync" + "testing" + + "github.com/devsy-org/devsy/internal/dependencytest" + "github.com/stretchr/testify/require" + "github.com/stretchr/testify/suite" +) + +const ( + metadataShortWrite = "short-write" + metadataCancelWrite = "cancel-write" + metadataCancelSync = "cancel-sync" + metadataCancelClose = "cancel-close" +) + +type MetadataWriterSuite struct{ suite.Suite } + +func TestMetadataWriter(t *testing.T) { suite.Run(t, new(MetadataWriterSuite)) } + +func metadataWriterFixture(t *testing.T) (*metadataWriter, string) { + t.Helper() + path := filepath.Join(t.TempDir(), "state") + require.NoError(t, os.Mkdir(path, 0o700)) + root, err := os.OpenRoot(path) + require.NoError(t, err) + t.Cleanup(func() { require.NoError(t, root.Close()) }) + writer, err := newMetadataWriter(root) + require.NoError(t, err) + return writer, path +} + +func (s *MetadataWriterSuite) TestPrivateStateAndInitialization() { + writer, path := metadataWriterFixture(s.T()) + entries, err := os.ReadDir(path) + s.Require().NoError(err) + s.Empty(entries, "constructor does not initialize the store") + s.Error(writer.writeJournal(s.T().Context(), metadataJournalFixture())) + s.Require().NoError(writer.initialize(s.T().Context())) + s.Require().NoError(writer.writeRegistry(s.T().Context(), metadataRegistryFixture())) + s.Require().NoError(writer.writeJournal(s.T().Context(), metadataJournalFixture())) + for _, name := range []string{"registry.json", "operations/operation-123.json"} { + info, err := os.Stat(filepath.Join(path, name)) + s.Require().NoError(err) + s.Equal(os.FileMode(0o600), info.Mode().Perm()) + } + info, err := os.Stat(filepath.Join(path, "operations")) + s.Require().NoError(err) + s.Equal(os.FileMode(0o700), info.Mode().Perm()) + missing := filepath.Join(path, "missing") + _, err = os.OpenRoot(missing) + s.ErrorIs(err, os.ErrNotExist) + _, err = os.Stat(missing) + s.ErrorIs(err, os.ErrNotExist) + s.Require().NoError(writer.root.Chmod(".", 0o755)) + _, err = newMetadataWriter(writer.root) + s.ErrorContains(err, "private") +} + +func (s *MetadataWriterSuite) TestFailuresBeforeReplacement() { + stages := []string{ + "write", + metadataShortWrite, + "sync", + "close", + "rename", + metadataCancelWrite, + metadataCancelSync, + metadataCancelClose, + } + for _, stage := range stages { + s.Run(stage, func() { s.assertFailureBeforeReplacement(stage) }) + } +} + +func injectMetadataFailure( + writer *metadataWriter, + stage string, + fault error, + cancel context.CancelFunc, +) { + switch stage { + case "write": + writer.hooks.write = func(*os.File, []byte) (int, error) { return 0, fault } + case metadataShortWrite: + writer.hooks.write = func(f *os.File, data []byte) (int, error) { return f.Write(data[:len(data)/2]) } + case "sync": + writer.hooks.sync = func(*os.File) error { return fault } + case "close": + writer.hooks.close = func(f *os.File) error { return errors.Join(f.Close(), fault) } + case "rename": + writer.hooks.rename = func(*os.Root, string, string) error { return fault } + case metadataCancelWrite, metadataCancelSync, metadataCancelClose: + injectMetadataCancellation(writer, stage, cancel) + } +} + +func (s *MetadataWriterSuite) TestPublishedDurabilityUncertainty() { + for _, stage := range []string{"directory-sync", "cancel-after-rename"} { + s.Run(stage, func() { + writer, path := metadataWriterFixture(s.T()) + s.Require().NoError(writer.writeRegistry(s.T().Context(), metadataRegistryFixture())) + ctx, cancel := context.WithCancel(s.T().Context()) + defer cancel() + if stage == "directory-sync" { + writer.hooks.syncDir = func(*os.Root) error { return errors.New("injected directory sync failure") } + } else { + writer.hooks.rename = func(root *os.Root, from, to string) error { + err := root.Rename(from, to) + cancel() + return err + } + } + next := metadataRegistryFixture() + next.Revision++ + err := writer.writeRegistry(ctx, next) + var commit *metadataCommitError + s.Require().ErrorAs(err, &commit) + s.True(commit.Published) + data, err := writer.root.ReadFile("registry.json") + s.Require().NoError(err) + decoded, err := DecodeRegistry(bytes.NewReader(data)) + s.Require().NoError(err) + s.Equal(next, decoded) + entries, err := os.ReadDir(path) + s.Require().NoError(err) + s.Len(entries, 1) + }) + } +} + +func (s *MetadataWriterSuite) TestFutureAndCorruptStatePreserved() { + originals := []string{ + `{"schemaVersion":42,"future":"must-survive"}`, `{"schemaVersion":42,"future":null}`, + `{"schemaVersion":1,"revision":1}`, "broken", + } + for _, original := range originals { + writer, path := metadataWriterFixture(s.T()) + target := filepath.Join(path, "registry.json") + s.Require().NoError(os.WriteFile(target, []byte(original), 0o600)) + err := writer.writeRegistry(s.T().Context(), metadataRegistryFixture()) + s.Require().Error(err) + if strings.Contains(original, `"schemaVersion":42`) { + var future *UnsupportedMetadataSchemaError + s.Require().ErrorAs(err, &future) + s.Equal(42, future.Version) + } + after, err := writer.root.ReadFile("registry.json") + s.Require().NoError(err) + s.Equal(original, string(after)) + } +} + +func (s *MetadataWriterSuite) TestDestinationAndParentSymlinks() { + external := s.T().TempDir() + sentinel := filepath.Join(external, "sentinel") + s.Require().NoError(os.WriteFile(sentinel, []byte("external runtime"), 0o600)) + dependencytest.Preserve(s.T(), external) + writer, path := metadataWriterFixture(s.T()) + s.Require().NoError(os.Symlink(sentinel, filepath.Join(path, "registry.json"))) + s.Error(writer.writeRegistry(s.T().Context(), metadataRegistryFixture())) + s.Require().NoError(os.Remove(filepath.Join(path, "registry.json"))) + s.Require().NoError(os.Symlink(external, filepath.Join(path, "operations"))) + s.Error(writer.initialize(s.T().Context())) + s.Error(writer.writeJournal(s.T().Context(), metadataJournalFixture())) +} + +func (s *MetadataWriterSuite) TestSubstitutionsAfterOpenAndBeforeRename() { + external := s.T().TempDir() + sentinel := filepath.Join(external, "sentinel") + s.Require().NoError(os.WriteFile(sentinel, []byte("external runtime"), 0o600)) + dependencytest.Preserve(s.T(), external) + writer, path := metadataWriterFixture(s.T()) + moved := path + "-pinned" + s.Require().NoError(os.Rename(path, moved)) + s.T().Cleanup(func() { s.Require().NoError(os.RemoveAll(moved)) }) + s.Require().NoError(os.Symlink(external, path)) + writer.hooks.rename = func(root *os.Root, from, to string) error { + if err := root.Symlink(sentinel, to); err != nil { + return err + } + return root.Rename(from, to) + } + s.Require().NoError(writer.writeRegistry(s.T().Context(), metadataRegistryFixture())) + data, err := writer.root.ReadFile("registry.json") + s.Require().NoError(err) + _, err = DecodeRegistry(bytes.NewReader(data)) + s.NoError(err) +} + +func (s *MetadataWriterSuite) TestOperationsDirectoryPinnedDuringWrite() { + external := s.T().TempDir() + s.Require().NoError(os.WriteFile(filepath.Join(external, "sentinel"), []byte("keep"), 0o600)) + dependencytest.Preserve(s.T(), external) + writer, path := metadataWriterFixture(s.T()) + s.Require().NoError(writer.initialize(s.T().Context())) + writer.hooks.write = func(file *os.File, data []byte) (int, error) { + if err := os.Rename( + filepath.Join(path, "operations"), + filepath.Join(path, "pinned"), + ); err != nil { + return 0, err + } + if err := os.Symlink(external, filepath.Join(path, "operations")); err != nil { + return 0, err + } + return file.Write(data) + } + s.Require().NoError(writer.writeJournal(s.T().Context(), metadataJournalFixture())) + data, err := writer.root.ReadFile("pinned/operation-123.json") + s.Require().NoError(err) + _, err = DecodeJournal(bytes.NewReader(data)) + s.NoError(err) +} + +func (s *MetadataWriterSuite) TestCancellationBeforeWriteHasNoEffects() { + writer, path := metadataWriterFixture(s.T()) + ctx, cancel := context.WithCancel(s.T().Context()) + cancel() + s.ErrorIs(writer.initialize(ctx), context.Canceled) + s.ErrorIs(writer.writeRegistry(ctx, metadataRegistryFixture()), context.Canceled) + entries, err := os.ReadDir(path) + s.Require().NoError(err) + s.Empty(entries) +} + +func (s *MetadataWriterSuite) TestCleanupPreservesUnrelatedTemporaryFiles() { + writer, path := metadataWriterFixture(s.T()) + unrelated := filepath.Join(path, ".metadata-someone-else.tmp") + s.Require().NoError(os.WriteFile(unrelated, []byte("keep"), 0o600)) + writer.hooks.sync = func(*os.File) error { return errors.New("sync failed") } + s.Error(writer.writeRegistry(s.T().Context(), metadataRegistryFixture())) + data, err := writer.root.ReadFile(".metadata-someone-else.tmp") + s.Require().NoError(err) + s.Equal("keep", string(data)) + entries, err := os.ReadDir(path) + s.Require().NoError(err) + s.Len(entries, 1) +} + +func (s *MetadataWriterSuite) TestAtomicReaders() { + writer, _ := metadataWriterFixture(s.T()) + s.Require().NoError(writer.writeRegistry(s.T().Context(), metadataRegistryFixture())) + var readers sync.WaitGroup + results := make(chan error, 1) + readers.Go(func() { + for range 100 { + data, err := writer.root.ReadFile("registry.json") + if err == nil { + _, err = DecodeRegistry(bytes.NewReader(data)) + } + if err != nil { + results <- err + return + } + } + }) + for revision := uint64(2); revision < 20; revision++ { + next := metadataRegistryFixture() + next.Revision = revision + s.Require().NoError(writer.writeRegistry(s.T().Context(), next)) + } + readers.Wait() + close(results) + for err := range results { + s.NoError(err) + } +} + +func (s *MetadataWriterSuite) TestLogicalMetadataNames() { + writer, _ := metadataWriterFixture(s.T()) + for _, destination := range []metadataDestination{ + {root: writer.root, name: metadataTraversalPath}, + {root: writer.root, name: "receipt.json"}, + {root: writer.root, name: "/registry.json"}, + {root: writer.root, name: "con.json", journal: true}, + {root: writer.root, name: "../operation.json", journal: true}, + } { + s.Error(writer.replace(s.T().Context(), destination, []byte("invalid"))) + } + s.Require().NoError(writer.initialize(s.T().Context())) + journal := metadataJournalFixture() + journal.OperationID = "registry" + s.Require().NoError(writer.writeJournal(s.T().Context(), journal)) + journal.Phase = PhaseDownloading + s.NoError(writer.writeJournal(s.T().Context(), journal)) +} + +func (s *MetadataWriterSuite) assertFailureBeforeReplacement(stage string) { + writer, path := metadataWriterFixture(s.T()) + old := metadataRegistryFixture() + s.Require().NoError(writer.writeRegistry(s.T().Context(), old)) + oldData, err := writer.root.ReadFile("registry.json") + s.Require().NoError(err) + ctx, cancel := context.WithCancel(s.T().Context()) + defer cancel() + sentinel := errors.New("injected " + stage) + injectMetadataFailure(writer, stage, sentinel, cancel) + next := old + next.Revision++ + err = writer.writeRegistry(ctx, next) + s.Require().Error(err) + expected := sentinel + if stage == metadataShortWrite { + expected = io.ErrShortWrite + } + if strings.HasPrefix(stage, "cancel-") { + expected = context.Canceled + } + s.ErrorIs(err, expected) + var commit *metadataCommitError + s.False(errors.As(err, &commit)) + after, err := writer.root.ReadFile("registry.json") + s.Require().NoError(err) + s.Equal(oldData, after) + entries, err := os.ReadDir(path) + s.Require().NoError(err) + s.Len(entries, 1, "only this attempt's temporary file is removed") +} + +func injectMetadataCancellation(writer *metadataWriter, stage string, cancel context.CancelFunc) { + switch stage { + case metadataCancelWrite: + writer.hooks.write = func(f *os.File, data []byte) (int, error) { n, err := f.Write(data); cancel(); return n, err } + case metadataCancelSync: + writer.hooks.sync = func(f *os.File) error { err := f.Sync(); cancel(); return err } + case metadataCancelClose: + writer.hooks.close = func(f *os.File) error { err := f.Close(); cancel(); return err } + } +} diff --git a/pkg/dependencies/metadata_write_unsupported.go b/pkg/dependencies/metadata_write_unsupported.go new file mode 100644 index 0000000000..67f7ce969b --- /dev/null +++ b/pkg/dependencies/metadata_write_unsupported.go @@ -0,0 +1,20 @@ +//go:build !linux && !darwin + +package dependencies + +import ( + "errors" + "os" +) + +func metadataWriteSupported() error { + return errors.New( + "atomic durable dependency metadata replacement is unsupported on this platform", + ) +} + +func validatePrivateMetadata(os.FileInfo) error { return metadataWriteSupported() } + +func openMetadataFile(*os.Root, string) (*os.File, error) { return nil, metadataWriteSupported() } + +func syncMetadataDirectory(*os.Root) error { return metadataWriteSupported() } diff --git a/pkg/dependencies/metadata_write_unsupported_test.go b/pkg/dependencies/metadata_write_unsupported_test.go new file mode 100644 index 0000000000..d925137d03 --- /dev/null +++ b/pkg/dependencies/metadata_write_unsupported_test.go @@ -0,0 +1,22 @@ +//go:build !linux && !darwin + +package dependencies + +import ( + "os" + "testing" + + "github.com/stretchr/testify/require" +) + +func TestMetadataWriterUnsupported(t *testing.T) { + path := t.TempDir() + root, err := os.OpenRoot(path) + require.NoError(t, err) + defer func() { require.NoError(t, root.Close()) }() + _, err = newMetadataWriter(root) + require.ErrorContains(t, err, "unsupported") + entries, err := os.ReadDir(path) + require.NoError(t, err) + require.Empty(t, entries) +} diff --git a/pkg/dependencies/receipt.go b/pkg/dependencies/receipt.go new file mode 100644 index 0000000000..3303355bb7 --- /dev/null +++ b/pkg/dependencies/receipt.go @@ -0,0 +1,112 @@ +package dependencies + +import ( + "errors" + "slices" + "strings" + "time" + + "github.com/blang/semver/v4" +) + +const ( + metadataRegular = "regular" + metadataExecutable = "msb" + metadataFirmware = "libkrunfw.so.5.6.1" +) + +// Receipt describes validated archive content, not current file identity, ownership, +// runtime readiness, or permission to execute or remove files. +type Receipt struct { + SchemaVersion int `json:"schemaVersion"` + Identity ReceiptIdentity `json:"identity"` + RecipeID string `json:"recipeId"` + RecipeSHA256 string `json:"recipeSha256"` + SourceURL string `json:"sourceUrl"` + InstalledAt time.Time `json:"installedAt"` + Layout string `json:"layout"` + Components []ReceiptComponent `json:"components"` + Validation ReceiptValidation `json:"validation"` +} + +// ReceiptIdentity names an immutable bundle using the full archive digest. +type ReceiptIdentity struct { + ToolID string `json:"toolId"` + RuntimeVersion string `json:"runtimeVersion"` + Platform string `json:"platform"` + ArchiveSHA256 string `json:"archiveSha256"` +} + +type ReceiptComponent struct { + Path string `json:"path"` + Type string `json:"type"` + SHA256 string `json:"sha256"` + Size int64 `json:"size"` +} + +// ReceiptValidation records only staging checks; it is not a live verification. +type ReceiptValidation struct { + Archive string `json:"archive"` + Layout string `json:"layout"` +} + +func (r Receipt) validate() error { + if err := r.Identity.validate(); err != nil { + return err + } + if !plainName(r.RecipeID) || !validSHA256(r.RecipeSHA256) || !metadataTime(r.InstalledAt) { + return errors.New("invalid receipt recipe identity or installation time") + } + if err := r.validateSource(); err != nil { + return err + } + return r.validateLayout() +} + +func (r Receipt) validateSource() error { + expectedSource := "https://github.com/superradcompany/microsandbox/releases/download/v" + + strings.TrimPrefix(r.Identity.RuntimeVersion, "v") + "/microsandbox-linux-x86_64.tar.gz" + if r.SourceURL != expectedSource { + return errors.New( + "receipt source must name the canonical credential-free upstream release asset", + ) + } + return nil +} + +func (r Receipt) validateLayout() error { + if r.Layout != "flat_verbatim_no_links" || len(r.Components) != 2 { + return errors.New("unsupported receipt layout or component inventory") + } + if r.Validation != (ReceiptValidation{Archive: "sha256_verified", Layout: "validated"}) { + return errors.New("receipt requires successful archive and layout validation") + } + return validateReceiptComponents(r.Components) +} + +func (id ReceiptIdentity) validate() error { + if id.ToolID != toolMicrosandbox || id.Platform != platformLinuxAMD64 || + !validSHA256(id.ArchiveSHA256) { + return errors.New("unsupported receipt tool/platform or invalid archive digest") + } + if _, err := semver.Parse(strings.TrimPrefix(id.RuntimeVersion, "v")); err != nil { + return errors.New("invalid receipt runtime semver") + } + return nil +} + +func validateReceiptComponents(components []ReceiptComponent) error { + seen := make(map[string]bool) + for _, component := range components { + if !slices.Contains([]string{metadataExecutable, metadataFirmware}, component.Path) || + seen[component.Path] { + return errors.New("receipt requires the reviewed flat msb and versioned firmware pair") + } + seen[component.Path] = true + if component.Type != metadataRegular || !validSHA256(component.SHA256) || + component.Size <= 0 { + return errors.New("receipt component must be a hashed, nonempty regular file") + } + } + return nil +} diff --git a/pkg/dependencies/registry.go b/pkg/dependencies/registry.go new file mode 100644 index 0000000000..eea3c3ca3b --- /dev/null +++ b/pkg/dependencies/registry.go @@ -0,0 +1,33 @@ +package dependencies + +import "errors" + +// Registry is an inventory snapshot. Revision is metadata for a later locked +// transaction; encoding or atomically replacing it does not perform CAS. +type Registry struct { + SchemaVersion int `json:"schemaVersion"` + Revision uint64 `json:"revision"` + Receipts []ReceiptIdentity `json:"receipts"` +} + +func (r Registry) validate() error { + if r.Revision == 0 || r.Receipts == nil || len(r.Receipts) > maxMetadataReferences { + return errors.New("registry requires a positive revision and bounded receipt inventory") + } + return validateReceiptIdentities(r.Receipts) +} + +func validateReceiptIdentities(identities []ReceiptIdentity) error { + bundles := make(map[string]bool) + for _, identity := range identities { + if err := identity.validate(); err != nil { + return err + } + key := identity.Platform + "/" + identity.ArchiveSHA256 + if bundles[key] { + return errors.New("duplicate immutable receipt identity") + } + bundles[key] = true + } + return nil +} diff --git a/pkg/dependencies/report.go b/pkg/dependencies/report.go new file mode 100644 index 0000000000..2b73a132c7 --- /dev/null +++ b/pkg/dependencies/report.go @@ -0,0 +1,371 @@ +package dependencies + +import ( + "errors" + "net/url" + "slices" + "strings" + "time" + "unicode" + "unicode/utf8" +) + +const ( + reportInvalid = "invalid passive dependency report input" + reportPodman = "podman" + reportKubernetes = "kubernetes" + reportIndirectLauncher = "indirect_launcher" +) + +// FormatPassiveReport converts trusted orchestration evidence without effects. +// Catalog identity and ContractVerified are consistency checks, not proof of an +// arbitrary caller-authored SurveyResult. Reobservation is required before use. +func (c *Catalog) FormatPassiveReport( + result SurveyResult, + metadata PassiveReportMetadata, +) (Report, error) { + binding, err := c.passiveReportBinding(result) + if err != nil { + return Report{}, err + } + if !validReportMetadata(result, metadata) || !validReportSurvey(result, binding) { + return Report{}, errors.New(reportInvalid) + } + item := formatReportItem(result.Requirements[0], metadata) + return Report{ + Schema: "devsy.dependencies.report.v1", + SchemaVersion: 1, + SurveyMode: "passive", + Target: ReportTarget{ + ContextName: result.Target.ContextName, + ProviderName: result.Target.ProviderName, + ProviderType: binding.Source.InternalID, + ProviderSourceID: "internal:" + binding.Source.InternalID, + ProviderSourceKind: "builtin_internal", + TrustedBuiltinIdentity: true, + ConfigRevision: result.Target.ConfigRevision, + ProviderConfigRevision: result.Target.ProviderConfigRevision, + EvaluatedAt: metadata.EvaluatedAt.UTC().Format(time.RFC3339Nano), + }, + Host: ReportHost{ + GOOS: result.Host.GOOS, GOARCH: result.Host.GOARCH, OSVersion: metadata.OSVersion, + VirtualizationCapability: metadata.VirtualizationCapability, + }, + Availability: item.Availability, + Compatibility: surveyUnknown, + Reachability: surveyNotChecked, + Policy: item.Policy, + ReasonCode: item.ReasonCode, + Message: "Passive inspection does not establish executable identity, version, compatibility, or readiness.", + Items: []ReportItem{item}, + Actions: []ReportAction{}, + }, nil +} + +func (c *Catalog) passiveReportBinding(result SurveyResult) (Binding, error) { + if c == nil || c.hash == "" { + return Binding{}, errors.New(reportInvalid) + } + if !c.validReportCatalog(result) { + return Binding{}, errors.New(reportInvalid) + } + for _, binding := range c.document.Bindings { + if binding.ID == result.BindingID && binding.Source.Kind == SourceInternal { + return binding, nil + } + } + return Binding{}, errors.New(reportInvalid) +} + +func (c *Catalog) validReportCatalog(result SurveyResult) bool { + return c.document.validate() == nil && result.CatalogID == c.ID() && + result.CatalogHash == c.Hash() +} + +func validReportMetadata(result SurveyResult, metadata PassiveReportMetadata) bool { + if metadata.Redact == nil || metadata.EvaluatedAt.IsZero() { + return false + } + for _, value := range []string{ + result.Target.ContextName, result.Target.ProviderName, + result.Target.ConfigRevision, result.Target.ProviderConfigRevision, + result.Host.GOOS, result.Host.GOARCH, metadata.VirtualizationCapability, + } { + if !safeReportIdentity(value, metadata.Redact) { + return false + } + } + if metadata.OSVersion != "" && !safeReportIdentity(metadata.OSVersion, metadata.Redact) { + return false + } + return validReportEvaluation(metadata) && validReportHost(result.Host, metadata) +} + +func validReportEvaluation(metadata PassiveReportMetadata) bool { + evaluatedAt := metadata.EvaluatedAt.UTC().Format(time.RFC3339Nano) + _, err := time.Parse(time.RFC3339Nano, evaluatedAt) + return err == nil && metadata.Redact(evaluatedAt) == evaluatedAt +} + +func validReportHost(host SurveyHost, metadata PassiveReportMetadata) bool { + if !slices.Contains([]string{"linux", "darwin", "windows"}, host.GOOS) || + !slices.Contains([]string{"amd64", "arm64"}, host.GOARCH) { + return false + } + if !slices.Contains([]string{ + "kvm_available", "kvm_unavailable", "hypervisor_framework", "not_required", "unsupported", + }, metadata.VirtualizationCapability) { + return false + } + return host.VirtualizationCapability == "" || + host.VirtualizationCapability == metadata.VirtualizationCapability +} + +func safeReportIdentity(value string, redact func(string) string) bool { + if strings.TrimSpace(value) == "" || !safeReportText(value, 4096) || redact(value) != value { + return false + } + parsed, err := url.Parse(value) + return err == nil && parsed.Scheme == "" && parsed.User == nil && + !strings.Contains(value, "://") +} + +func safeReportText(value string, limit int) bool { + return len(value) <= limit && utf8.ValidString(value) && !strings.ContainsRune(value, '@') && + strings.IndexFunc(value, func(character rune) bool { + return unicode.IsControl(character) || unicode.Is(unicode.Cf, character) + }) == -1 +} + +func validReportSurvey(result SurveyResult, binding Binding) bool { + if !validReportPassiveState(result) { + return false + } + item := result.Requirements[0] + return validReportPolicy(result, binding) && + sameReportRequirement(item.Requirement, binding.Requirements[0]) && + validReportRequirementState(item) && validReportObservation(item) +} + +func validReportPassiveState(result SurveyResult) bool { + return result.ContractVerified && !result.Executed && + result.AdapterStatus == "not_applicable" && + result.ManagedCapabilities == (SurveyManagedCapabilities{}) && + len(result.Requirements) == 1 +} + +func validReportPolicy(result SurveyResult, binding Binding) bool { + policyReason := "dependency_recipe_unqualified" + policy := surveyExternalOnly + if !slices.Contains(binding.Platforms, result.Host.GOOS+"/"+result.Host.GOARCH) { + policyReason, policy = surveyPlatformUnsupported, surveyUnsupported + } + item := result.Requirements[0] + return result.PolicyReason == policyReason && item.PolicyReason == policyReason && + item.Policy == policy +} + +func validReportRequirementState(item RequirementSurvey) bool { + return !item.Executed && item.Compatibility == surveyUnknown && + item.Reachability == surveyNotChecked +} + +func sameReportRequirement(actual, expected Requirement) bool { + return slices.Equal(actual.RequiredFor, expected.RequiredFor) && + actual.ToolID == expected.ToolID && actual.Purpose == expected.Purpose && actual.Scope == expected.Scope && + actual.ExecutableOption == expected.ExecutableOption && actual.ConfigurationOption == expected.ConfigurationOption && + sameReportGuidance(actual, expected) +} + +func sameReportGuidance(actual, expected Requirement) bool { + return actual.ProbeID == expected.ProbeID && actual.GuidanceID == expected.GuidanceID && + actual.WhenImageBackend == expected.WhenImageBackend +} + +func validReportObservation(item RequirementSurvey) bool { + if item.Requirement.ConfigurationOption != "" { + return len(item.Candidates) == 0 && item.Availability == surveyUnknown && + item.ReasonCode == surveyPolicyBlocked + } + if len(item.Candidates) == 0 { + return validReportEmptyLookup(item) + } + lookup, valid := reportLookupEvidence(item.Candidates) + if !valid { + return false + } + availability := surveyAvailability(lookup) + return item.Availability == availability && + item.ReasonCode == surveyObservationReason(lookup.ReasonCode, availability) +} + +func validReportEmptyLookup(item RequirementSurvey) bool { + return (item.Availability == surveyUnknown && item.ReasonCode == LookupInvalidPath) || + (item.Availability == surveyMissing && item.ReasonCode == LookupMissing) +} + +func reportLookupEvidence(candidates []ExecutableCandidate) (LookupResult, bool) { + lookup := LookupResult{Candidates: slices.Clone(candidates)} + for i, candidate := range lookup.Candidates { + if !validReportCandidate(candidate) || + !consistentReportOrigin(lookup.Candidates[0].Origin, candidate.Origin) { + return LookupResult{}, false + } + if candidate.State == FileDeferred { + lookup.Candidates[i].ReasonCode = LookupInspectionDeferred + } + } + explicit := lookup.Candidates[0].Origin == LookupExplicit || + lookup.Candidates[0].Origin == LookupExplicitEnv + lookup.finish(explicit) + return lookup, true +} + +func consistentReportOrigin(first, origin LookupOrigin) bool { + if first == LookupExplicit || first == LookupExplicitEnv { + return origin == first + } + return origin == LookupPATH || origin == LookupReviewed +} + +func validReportCandidate(candidate ExecutableCandidate) bool { + if candidate.Executed || !slices.Contains([]LookupOrigin{ + LookupExplicit, LookupExplicitEnv, LookupPATH, LookupReviewed, + }, candidate.Origin) { + return false + } + reason := "" + switch candidate.State { + case FileDeferred: + reason = surveyPolicyBlocked + case FileExecutable, FileNonregular, FileNonexecutable: + if candidate.Launcher { + reason = LookupIndirectLauncher + } + case FileMissing, FileBrokenLink, FileInaccessible: + default: + return false + } + return candidate.ReasonCode == reason +} + +func formatReportItem(item RequirementSurvey, metadata PassiveReportMetadata) ReportItem { + output := ReportItem{ + ID: item.Requirement.ToolID, + DisplayName: reportToolLabel(item.Requirement.ToolID), + Required: true, + Availability: item.Availability, + Compatibility: surveyUnknown, + Reachability: surveyNotChecked, + Policy: item.Policy, + ReasonCode: item.ReasonCode, + Candidates: []ReportCandidate{}, + } + suppressed := false + for _, candidate := range item.Candidates { + if !safeReportCandidatePaths(candidate, metadata.Redact) { + suppressed = true + continue + } + output.Candidates = append( + output.Candidates, + formatReportCandidate(candidate, item.Requirement), + ) + } + return finishReportItem(output, item, suppressed) +} + +func finishReportItem(output ReportItem, item RequirementSurvey, suppressed bool) ReportItem { + if suppressed || item.Availability == surveyAvailable { + output.Availability, output.ReasonCode = surveyUnknown, surveyPolicyBlocked + } else if item.Availability != surveyUnknown || len(item.Candidates) > 0 { + output.ReasonCode = surveyUnavailableReason(item.Availability) + } + if !suppressed && item.ReasonCode == LookupIndirectLauncher { + output.ReasonCode = LookupIndirectLauncher + } + if item.Policy == surveyUnsupported { + output.ReasonCode = surveyPlatformUnsupported + } + return output +} + +func formatReportCandidate(candidate ExecutableCandidate, requirement Requirement) ReportCandidate { + availability := surveyFileAvailability(candidate.State) + reason := surveyUnavailableReason(availability) + detail := "" + if candidate.State == FileExecutable { + availability, reason = surveyUnknown, surveyPolicyBlocked + detail = "Serialized file identity is unavailable; executable metadata does not establish usable availability." + } + source := string(candidate.Origin) + if candidate.Launcher { + source, reason = reportIndirectLauncher, LookupIndirectLauncher + } + return ReportCandidate{ + Component: requirement.ToolID, + SourceKind: source, + OptionName: reportCandidateOption(candidate.Origin, requirement.ExecutableOption), + LexicalPath: candidate.LexicalPath, + ResolvedPath: candidate.ResolvedPath, + IsSymlink: candidate.IsSymlink, + Availability: availability, + Compatibility: surveyUnknown, + ReasonCode: reason, + Detail: detail, + } +} + +func reportCandidateOption(origin LookupOrigin, option string) string { + if origin == LookupExplicit || origin == LookupExplicitEnv { + return option + } + return "" +} + +func reportToolLabel(tool string) string { + switch tool { + case toolDocker: + return "Docker" + case reportPodman: + return "Podman" + case "apple-container": + return "Apple Container" + default: + return "Kubernetes configuration" + } +} + +func safeReportPath(value string, redact func(string) string) bool { + if strings.TrimSpace(value) == "" || !safeReportText(value, 32768) || redact(value) != value { + return false + } + // Native absolute paths can contain tools:// as a directory spelling. Parse + // URI syntax only after recognizing native roots, without cleaning the path. + if reportNativeRoot(value) { + return true + } + parsed, err := url.Parse(value) + return err == nil && parsed.Scheme == "" && parsed.User == nil && + !strings.Contains(value, "://") +} + +func safeReportCandidatePaths(candidate ExecutableCandidate, redact func(string) string) bool { + return safeReportPath(candidate.LexicalPath, redact) && + (candidate.ResolvedPath == "" || safeReportPath(candidate.ResolvedPath, redact)) +} + +func reportNativeRoot(value string) bool { + if strings.HasPrefix(value, "/") || strings.HasPrefix(value, `\\`) { + return true + } + if len(value) >= 3 && isReportDriveLetter(value[0]) && value[1] == ':' && + strings.ContainsAny(value[2:3], `/\`) { + return true + } + return false +} + +func isReportDriveLetter(letter byte) bool { + return letter >= 'A' && letter <= 'Z' || letter >= 'a' && letter <= 'z' +} diff --git a/pkg/dependencies/report_contracts_test.go b/pkg/dependencies/report_contracts_test.go new file mode 100644 index 0000000000..8e2373768b --- /dev/null +++ b/pkg/dependencies/report_contracts_test.go @@ -0,0 +1,278 @@ +package dependencies_test + +import ( + "context" + "encoding/json" + "os" + "path/filepath" + "runtime" + "time" + + "github.com/devsy-org/devsy/internal/dependencytest" + "github.com/devsy-org/devsy/pkg/dependencies" +) + +const contractExecutablePath = "/tools/docker" + +func passiveContractMetadata() dependencies.PassiveReportMetadata { + return dependencies.PassiveReportMetadata{ + EvaluatedAt: time.Date(2026, time.October, 19, 12, 0, 0, 0, time.UTC), + VirtualizationCapability: "not_required", + Redact: func(value string) string { return value }, + } +} + +func (s *contractsSuite) passiveSurvey( + bindingID, path string, +) (*dependencies.Catalog, dependencies.SurveyResult) { + catalog, err := dependencies.LoadCatalog() + s.Require().NoError(err) + root := s.T().TempDir() + environment, err := dependencies.NewLookupEnvironment(map[string]string{"PATH": ""}, root) + s.Require().NoError(err) + request := dependencies.SurveyRequest{ + Target: dependencies.SurveyTarget{ + ContextName: "actual-context", ProviderName: "renamed-production-installation", + ConfigRevision: "config-snapshot-17", ProviderConfigRevision: "provider-snapshot-23", + }, + Host: dependencies.SurveyHost{GOOS: runtime.GOOS, GOARCH: runtime.GOARCH}, + Environment: environment, Options: map[string]dependencies.SurveyOption{}, + } + for _, binding := range catalog.Bindings() { + if binding.ID == bindingID { + request.Contract = dependencies.ProviderContract{ + Source: binding.Source, + ExecutionContract: binding.ExecutionContract, + } + request.Options[binding.Requirements[0].ExecutableOption] = dependencies.SurveyOption{ + Value: path, UserProvided: true, Origin: dependencies.LookupExplicitEnv, + } + } + } + result, err := catalog.Survey(context.Background(), request) + s.Require().NoError(err) + return catalog, result +} + +func (s *contractsSuite) passiveContract( + catalog *dependencies.Catalog, + result dependencies.SurveyResult, +) *reportContract { + report, err := catalog.FormatPassiveReport(result, passiveContractMetadata()) + s.Require().NoError(err) + raw, err := json.Marshal(report) + s.Require().NoError(err) + decoded, err := s.decodeAndValidateRaw(raw) + s.Require().NoError(err) + for _, absent := range []string{ + `"observation"`, `"fileIdentity"`, `"selectedPair"`, `"managedRecipe"`, `"adapterVersion"`, + `"staleAgainstRevision"`, `"platform"`, `:null`, + } { + s.NotContains(string(raw), absent) + } + s.Contains(string(raw), `"actions":[]`) + s.Equal(result.Target.ProviderName, decoded.Target.ProviderName) + s.Empty(decoded.Actions) + return decoded +} + +func (s *contractsSuite) TestPassiveReportRealSurveyContractsAndPreservation() { + if runtime.GOOS == osWindows { + s.T().Skip("Unix sentinel, execute bits, and symlinks; Windows evidence is compile-only") + } + root := s.T().TempDir() + marker := filepath.Join(root, "EXECUTED") + executable := filepath.Join(root, "docker") + s.Require(). + NoError(os.WriteFile(executable, []byte("#!/bin/sh\nprintf executed > '"+marker+"'\n"), 0o600)) + info, err := os.Stat(executable) + s.Require().NoError(err) + s.Require().NoError(os.Chmod(executable, info.Mode()|0o100)) + plain := filepath.Join(root, "nonexec") + s.Require().NoError(os.WriteFile(plain, []byte("not executable"), 0o600)) + missing := filepath.Join(root, "missing") + link := filepath.Join(root, "broken") + s.Require().NoError(os.Symlink(missing, link)) + dependencytest.Preserve(s.T(), root) + for _, binding := range []string{providerDocker, providerPodman, providerApple, providerKubernetes} { + for _, path := range []string{executable, plain, missing, link, "", "https://user:secret@host/tool"} { + catalog, result := s.passiveSurvey(binding, path) + report := s.passiveContract(catalog, result) + s.Equal(binding, report.Target.ProviderType) + s.Equal("internal:"+binding, report.Target.ProviderSourceID) + s.NotEqual(availabilityAvailable, report.Availability) + if binding == providerKubernetes { + s.Empty(report.Items[0].Candidates) + s.Equal(availabilityUnknown, report.Availability) + } else if path == executable { + s.Require().NotNil(result.Requirements[0].Candidates[0].Identity) + s.Equal(availabilityUnknown, report.Availability) + } + } + } + s.NoFileExists(marker) +} + +func (s *contractsSuite) TestPassiveReportAllFileStatesPassFrozenValidators() { + states := []struct { + state dependencies.FileState + availability string + reason string + }{ + {dependencies.FileExecutable, string(availabilityAvailable), string(reasonVersionUnknown)}, + {dependencies.FileMissing, "missing", "dependency_missing"}, + {dependencies.FileBrokenLink, string(availabilityIncomplete), string(reasonIncomplete)}, + {dependencies.FileNonregular, string(availabilityIncomplete), string(reasonIncomplete)}, + {dependencies.FileNonexecutable, string(availabilityIncomplete), string(reasonIncomplete)}, + {dependencies.FileInaccessible, "unknown", string(reasonPolicyBlocked)}, + {dependencies.FileDeferred, "unknown", string(reasonPolicyBlocked)}, + } + for _, state := range states { + for _, origin := range []dependencies.LookupOrigin{ + dependencies.LookupExplicit, dependencies.LookupExplicitEnv, dependencies.LookupPATH, dependencies.LookupReviewed, + } { + catalog, result := s.passiveSurvey(providerDocker, "") + item := &result.Requirements[0] + item.Availability, item.ReasonCode = state.availability, state.reason + candidate := dependencies.ExecutableCandidate{ + Origin: origin, + State: state.state, + LexicalPath: contractExecutablePath, + ResolvedPath: contractExecutablePath, + } + if state.state == dependencies.FileDeferred { + candidate.ReasonCode = string(reasonPolicyBlocked) + } + if origin == dependencies.LookupExplicit || origin == dependencies.LookupExplicitEnv { + if state.state != dependencies.FileExecutable && + state.state != dependencies.FileDeferred { + item.ReasonCode = "dependency_path_invalid" + } + } + item.Candidates = []dependencies.ExecutableCandidate{candidate} + s.passiveContract(catalog, result) + } + } +} + +func (s *contractsSuite) TestPassiveReportGeneratedNegativeContracts() { + catalog, result := s.passiveSurvey(providerDocker, "") + item := &result.Requirements[0] + item.Availability, item.ReasonCode = string(availabilityAvailable), string(reasonVersionUnknown) + item.Candidates = []dependencies.ExecutableCandidate{{ + Origin: dependencies.LookupPATH, State: dependencies.FileExecutable, + LexicalPath: contractExecutablePath, ResolvedPath: contractExecutablePath, + }} + generated := s.passiveContract(catalog, result) + mutations := map[string]func(*reportContract){ + "available without identity": func(r *reportContract) { + r.Items[0].Candidates[0].Availability = availabilityAvailable + }, + "path identity": func(r *reportContract) { + c := &r.Items[0].Candidates[0] + c.Availability = availabilityAvailable + c.Observation = &candidateFileObservation{FileIdentity: c.LexicalPath} + }, + "revision identity": func(r *reportContract) { + c := &r.Items[0].Candidates[0] + c.Availability = availabilityAvailable + c.Observation = &candidateFileObservation{FileIdentity: r.Target.ConfigRevision} + }, + "passive version": func(r *reportContract) { + c := &r.Items[0].Candidates[0] + c.Availability = availabilityAvailable + c.Observation = &candidateFileObservation{ + FileIdentity: "opaque-fixture-identity", + ObservedVersion: "1.2.3", + } + }, + "compatible": func(r *reportContract) { r.Items[0].Candidates[0].Compatibility = compatibilityCompatible }, + "selection": func(r *reportContract) { r.Items[0].Candidates[0].Selected = true }, + "managed action": func(r *reportContract) { + r.Actions = []remediationAction{{ + Kind: actionInstall, Label: "Install", Enabled: true, + RequiresEffectAuthorization: true, RequiresConfirmation: true, + }} + }, + } + for name, mutate := range mutations { + s.Run(name, func() { + changed := cloneReport(s.T(), generated) + mutate(changed) + raw, err := json.Marshal(changed) + s.Require().NoError(err) + _, err = s.decodeAndValidateRaw(raw) + s.Require().Error(err) + }) + } +} + +func (s *contractsSuite) TestPassiveReportLauncherSuppressionAndPlatformContracts() { + catalog, result := s.passiveSurvey(providerApple, "") + result.Host = dependencies.SurveyHost{GOOS: osLinux, GOARCH: archAMD64} + result.PolicyReason = string(reasonPlatformUnsupported) + item := &result.Requirements[0] + item.PolicyReason, item.Policy = string(reasonPlatformUnsupported), string(policyUnsupported) + item.Availability, item.ReasonCode = string( + availabilityAvailable, + ), string( + reasonIndirectLauncher, + ) + item.Candidates = []dependencies.ExecutableCandidate{ + { + Origin: dependencies.LookupExplicitEnv, + State: dependencies.FileExecutable, + LexicalPath: "/mise/shims/container", + Launcher: true, + ReasonCode: string(reasonIndirectLauncher), + }, + } + report := s.passiveContract(catalog, result) + s.Equal(reasonPlatformUnsupported, report.ReasonCode) + s.Equal(availabilityUnknown, report.Availability) + s.Equal(candidateSourceIndirectLauncher, report.Items[0].Candidates[0].SourceKind) + s.Equal(reasonIndirectLauncher, report.Items[0].Candidates[0].ReasonCode) + item.Candidates[0].LexicalPath = "https://user:secret@host/container" + report = s.passiveContract(catalog, result) + s.Equal(reasonPlatformUnsupported, report.ReasonCode) + s.Equal(availabilityUnknown, report.Availability) + s.Empty(report.Items[0].Candidates) +} + +func (s *contractsSuite) TestPassiveReportLauncherAndRedactionContracts() { + catalog, result := s.passiveSurvey(providerDocker, "") + item := &result.Requirements[0] + item.Availability, item.ReasonCode = string( + availabilityAvailable, + ), string( + reasonIndirectLauncher, + ) + item.Candidates = []dependencies.ExecutableCandidate{ + { + Origin: dependencies.LookupPATH, + State: dependencies.FileExecutable, + LexicalPath: "/mise/shims/docker", + Launcher: true, + ReasonCode: string(reasonIndirectLauncher), + }, + } + report := s.passiveContract(catalog, result) + s.Equal(reasonIndirectLauncher, report.ReasonCode) + s.False(report.Items[0].Candidates[0].Selected) + metadata := passiveContractMetadata() + metadata.Redact = func(value string) string { + if value == "/mise/shims/docker" { + return "" + } + return value + } + output, err := catalog.FormatPassiveReport(result, metadata) + s.Require().NoError(err) + raw, err := json.Marshal(output) + s.Require().NoError(err) + decoded, err := s.decodeAndValidateRaw(raw) + s.Require().NoError(err) + s.Equal(reasonPolicyBlocked, decoded.ReasonCode) + s.Equal(availabilityUnknown, decoded.Availability) + s.Empty(decoded.Items[0].Candidates) +} diff --git a/pkg/dependencies/report_test.go b/pkg/dependencies/report_test.go new file mode 100644 index 0000000000..82c22f31a1 --- /dev/null +++ b/pkg/dependencies/report_test.go @@ -0,0 +1,310 @@ +package dependencies + +import ( + "encoding/json" + "strings" + "testing" + "time" + + "github.com/stretchr/testify/suite" +) + +const ( + reportTestPath = "/tools/docker" + reportTestIgnored = "ignored-private-fragment" + reportTestOther = "other" + reportTestUnreviewed = "unreviewed secret" + reportTestIncomplete = "dependency_incomplete" +) + +type reportSuite struct { + suite.Suite + catalog *Catalog +} + +func TestPassiveReport(t *testing.T) { suite.Run(t, new(reportSuite)) } + +func (s *reportSuite) SetupTest() { + var err error + s.catalog, err = LoadCatalog() + s.Require().NoError(err) +} + +func reportMetadata() PassiveReportMetadata { + return PassiveReportMetadata{ + EvaluatedAt: time.Date( + 2026, + time.October, + 19, + 12, + 30, + 40, + 123, + time.FixedZone("offset", -21600), + ), + VirtualizationCapability: "not_required", + Redact: func(value string) string { return value }, + } +} + +func (s *reportSuite) TestBindingsAndExplicitMetadata() { + for _, binding := range []string{"docker", reportPodman, "apple", reportKubernetes} { + result := s.result(binding) + report := s.format(result, reportMetadata()) + s.Equal(binding, report.Target.ProviderType) + s.Equal("internal:"+binding, report.Target.ProviderSourceID) + s.Equal(result.Target.ProviderName, report.Target.ProviderName) + s.Equal(result.Target.ContextName, report.Target.ContextName) + s.Equal(result.Target.ConfigRevision, report.Target.ConfigRevision) + s.Equal(result.Target.ProviderConfigRevision, report.Target.ProviderConfigRevision) + s.Equal("2026-10-19T18:30:40.000000123Z", report.Target.EvaluatedAt) + s.Equal("not_required", report.Host.VirtualizationCapability) + s.Empty(report.Actions) + s.NotNil(report.Actions) + s.NotNil(report.Items[0].Candidates) + } +} + +func (s *reportSuite) TestHostFactsAreExplicitAndPreserved() { + for _, goos := range []string{"linux", "darwin", "windows"} { + for _, goarch := range []string{"amd64", "arm64"} { + for _, capability := range []string{ + "kvm_available", "kvm_unavailable", "hypervisor_framework", "not_required", "unsupported", + } { + result, metadata := s.result(toolDocker), reportMetadata() + result.Host = SurveyHost{ + GOOS: goos, + GOARCH: goarch, + VirtualizationCapability: capability, + } + metadata.VirtualizationCapability, metadata.OSVersion = capability, "15.2 (24C101)" + report := s.format(result, metadata) + s.Equal(goos, report.Host.GOOS) + s.Equal(goarch, report.Host.GOARCH) + s.Equal(capability, report.Host.VirtualizationCapability) + s.Equal(metadata.OSVersion, report.Host.OSVersion) + } + } + } +} + +func (s *reportSuite) TestEveryFileStateAndOrigin() { + for _, test := range []struct { + state FileState + availability string + reason string + }{ + {FileExecutable, surveyUnknown, surveyPolicyBlocked}, + {FileMissing, surveyMissing, LookupMissing}, + {FileBrokenLink, surveyIncomplete, reportTestIncomplete}, + {FileNonregular, surveyIncomplete, reportTestIncomplete}, + {FileNonexecutable, surveyIncomplete, reportTestIncomplete}, + {FileInaccessible, surveyUnknown, surveyPolicyBlocked}, + {FileDeferred, surveyUnknown, surveyPolicyBlocked}, + } { + for _, origin := range []LookupOrigin{LookupExplicit, LookupExplicitEnv, LookupPATH, LookupReviewed} { + result := s.result("docker") + candidate := ExecutableCandidate{ + Origin: origin, + LexicalPath: reportTestPath, + State: test.state, + } + if test.state == FileDeferred { + candidate.ReasonCode = LookupInspectionDeferred + } + s.observe(&result, candidate) + report := s.format(result, reportMetadata()) + output := report.Items[0].Candidates[0] + s.Equal(string(origin), output.SourceKind) + s.Equal(reportCandidateOption(origin, "DOCKER_PATH"), output.OptionName) + if test.state == FileExecutable { + s.Contains(output.Detail, "Serialized file identity is unavailable") + } + s.Equal(test.availability, output.Availability) + s.Equal(test.availability, report.Availability) + s.Equal(test.reason, output.ReasonCode) + s.Equal(test.reason, report.ReasonCode) + s.False(output.Selected) + s.False(output.Executed) + } + } +} + +func (s *reportSuite) TestLauncherAndUnsupportedPolicy() { + result := s.result("apple") + result.Host = SurveyHost{GOOS: "linux", GOARCH: "amd64"} + result.PolicyReason = surveyPlatformUnsupported + result.Requirements[0].PolicyReason = surveyPlatformUnsupported + result.Requirements[0].Policy = surveyUnsupported + s.observe(&result, ExecutableCandidate{ + Origin: LookupExplicitEnv, + LexicalPath: "/mise/shims/container", + ResolvedPath: "/mise/shims/container", + State: FileExecutable, + Launcher: true, + ReasonCode: LookupIndirectLauncher, + }) + report := s.format(result, reportMetadata()) + s.Equal(surveyUnknown, report.Availability) + s.Equal(surveyUnsupported, report.Policy) + s.Equal(surveyPlatformUnsupported, report.ReasonCode) + s.Equal(surveyPlatformUnsupported, report.Items[0].ReasonCode) + s.Equal(reportIndirectLauncher, report.Items[0].Candidates[0].SourceKind) + s.Equal(LookupIndirectLauncher, report.Items[0].Candidates[0].ReasonCode) +} + +func (s *reportSuite) TestSuppressionIsUnknownAndNeverPartialPath() { + for _, path := range []string{ + "https://user:private-fragment@host/docker", "ssh://host/docker", "file://host/docker", + `C:\user:private-fragment@host\docker.exe`, "/tools/line\nfeed", "/tools/\u202edocker", "/private-fragment/docker", + } { + for _, resolved := range []bool{false, true} { + result := s.result("docker") + candidate := ExecutableCandidate{ + Origin: LookupPATH, + State: FileMissing, + LexicalPath: path, + } + if resolved { + candidate.LexicalPath, candidate.ResolvedPath = "/safe/docker", path + } + s.observe(&result, candidate) + metadata := reportMetadata() + metadata.Redact = func(value string) string { return strings.ReplaceAll(value, "private-fragment", "REDACTED") } + report := s.format(result, metadata) + s.Equal(surveyUnknown, report.Availability) + s.Equal(surveyPolicyBlocked, report.ReasonCode) + s.Empty(report.Items[0].Candidates) + encoded, err := json.Marshal(report) + s.Require().NoError(err) + s.NotContains(string(encoded), "private-fragment") + s.NotContains(string(encoded), "REDACTED") + } + } +} + +func (s *reportSuite) TestNativeSpellingAndRefusingPathPolicy() { + for _, path := range []string{"/tmp/tools://docker", `C:\tools\docker.exe`, `\\server\tools\docker.exe`} { + result := s.result("docker") + s.observe(&result, ExecutableCandidate{ + Origin: LookupReviewed, + State: FileExecutable, + LexicalPath: path, + ResolvedPath: path, + IsSymlink: true, + }) + report := s.format(result, reportMetadata()) + s.Equal(path, report.Items[0].Candidates[0].LexicalPath) + s.Equal(path, report.Items[0].Candidates[0].ResolvedPath) + s.True(report.Items[0].Candidates[0].IsSymlink) + metadata := reportMetadata() + metadata.Redact = func(value string) string { + if value == path { + return "" + } + return value + } + report = s.format(result, metadata) + s.Equal(surveyUnknown, report.Availability) + s.Empty(report.Items[0].Candidates) + } +} + +func (s *reportSuite) TestInvalidExplicitWithoutCandidates() { + result := s.result("docker") + result.Requirements[0].Availability = surveyUnknown + result.Requirements[0].ReasonCode = LookupInvalidPath + report := s.format(result, reportMetadata()) + s.Equal(LookupInvalidPath, report.ReasonCode) + s.Empty(report.Items[0].Candidates) +} + +func (s *reportSuite) TestNoSliceAliasingOrAmbientEvidence() { + result := s.result("docker") + result.Target.StoreID = reportTestIgnored + result.Target.ProviderFingerprint = reportTestIgnored + result.Host.NativeArchitecture = reportTestIgnored + s.observe(&result, ExecutableCandidate{ + Origin: LookupPATH, + State: FileExecutable, + LexicalPath: reportTestPath, + ResolvedPath: reportTestPath, + Platform: reportTestIgnored, + Identity: &FileObservation{}, + }) + first := s.format(result, reportMetadata()) + second := s.format(result, reportMetadata()) + first.Items[0].Candidates[0].LexicalPath = "mutated" + first.Items[0].ID = "mutated" + s.Equal(reportTestPath, result.Requirements[0].Candidates[0].LexicalPath) + s.Equal(reportTestPath, second.Items[0].Candidates[0].LexicalPath) + s.Equal("docker", result.Requirements[0].Requirement.ToolID) + encoded, err := json.Marshal(second) + s.Require().NoError(err) + for _, absent := range []string{ + "observation", "fileIdentity", "observedVersion", "selectedPair", "managedRecipe", "adapterVersion", + "staleAgainstRevision", reportTestIgnored, `"platform"`, `:null`, + } { + s.NotContains(string(encoded), absent) + } +} + +func (s *reportSuite) result(bindingID string) SurveyResult { + var binding Binding + for _, candidate := range s.catalog.Bindings() { + if candidate.ID == bindingID { + binding = candidate + } + } + s.Require().NotEmpty(binding.ID) + result := SurveyResult{ + Target: SurveyTarget{ + ContextName: "Work context", ProviderName: "Renamed installation", + ConfigRevision: "snapshot-one", ProviderConfigRevision: "provider-two", + }, + Host: SurveyHost{GOOS: "darwin", GOARCH: "arm64"}, + CatalogID: s.catalog.ID(), + CatalogHash: s.catalog.Hash(), + BindingID: binding.ID, + ContractVerified: true, + AdapterStatus: "not_applicable", + PolicyReason: "dependency_recipe_unqualified", + Requirements: []RequirementSurvey{ + { + Requirement: binding.Requirements[0], + Availability: surveyMissing, + Compatibility: surveyUnknown, + Reachability: surveyNotChecked, + Policy: surveyExternalOnly, + PolicyReason: "dependency_recipe_unqualified", + ReasonCode: LookupMissing, + }, + }, + } + if bindingID == reportKubernetes { + result.Requirements[0].Availability = surveyUnknown + result.Requirements[0].ReasonCode = surveyPolicyBlocked + } + return result +} + +func (s *reportSuite) observe(result *SurveyResult, candidates ...ExecutableCandidate) { + item := &result.Requirements[0] + item.Candidates = candidates + lookup := LookupResult{Candidates: candidates} + lookup.finish(len(candidates) > 0 && + (candidates[0].Origin == LookupExplicit || candidates[0].Origin == LookupExplicitEnv)) + item.Availability = surveyAvailability(lookup) + item.ReasonCode = surveyObservationReason(lookup.ReasonCode, item.Availability) + for i := range item.Candidates { + if item.Candidates[i].ReasonCode == LookupInspectionDeferred { + item.Candidates[i].ReasonCode = surveyPolicyBlocked + } + } +} + +func (s *reportSuite) format(result SurveyResult, metadata PassiveReportMetadata) Report { + report, err := s.catalog.FormatPassiveReport(result, metadata) + s.Require().NoError(err) + return report +} diff --git a/pkg/dependencies/report_types.go b/pkg/dependencies/report_types.go new file mode 100644 index 0000000000..a7fc56b4c9 --- /dev/null +++ b/pkg/dependencies/report_types.go @@ -0,0 +1,92 @@ +package dependencies + +import "time" + +// PassiveReportMetadata supplies facts that passive lookup cannot establish. +// Redact must be deterministic and side-effect-free. VirtualizationCapability +// must be an explicit caller assertion, including when it is not_required. +// Revisions in SurveyTarget identify snapshots, not files or CAS authority. +type PassiveReportMetadata struct { + EvaluatedAt time.Time + OSVersion string + VirtualizationCapability string + Redact func(string) string +} + +// Report is the bounded passive subset of the frozen v1 wire contract. +// Its mutable values confer no execution, selection, or installation authority. +type Report struct { + Schema string `json:"schema"` + SchemaVersion int `json:"schemaVersion"` + SurveyMode string `json:"surveyMode"` + Executed bool `json:"executed"` + Target ReportTarget `json:"target"` + Host ReportHost `json:"host"` + Availability string `json:"availability"` + Compatibility string `json:"compatibility"` + Reachability string `json:"reachability"` + Policy string `json:"policy"` + ReasonCode string `json:"reasonCode"` + Message string `json:"message"` + Items []ReportItem `json:"items"` + Actions []ReportAction `json:"actions"` +} + +type ReportTarget struct { + ContextName string `json:"contextName"` + ProviderName string `json:"providerName"` + ProviderType string `json:"providerType"` + ProviderSourceID string `json:"providerSourceId"` + ProviderSourceKind string `json:"providerSourceKind"` + TrustedBuiltinIdentity bool `json:"trustedBuiltinIdentity"` + ConfigRevision string `json:"configRevision"` + ProviderConfigRevision string `json:"providerConfigRevision"` + EvaluatedAt string `json:"evaluatedAt"` +} + +type ReportHost struct { + GOOS string `json:"goos"` + GOARCH string `json:"goarch"` + OSVersion string `json:"osVersion,omitempty"` + VirtualizationCapability string `json:"virtualizationCapability"` +} + +type ReportItem struct { + ID string `json:"id"` + DisplayName string `json:"displayName"` + Required bool `json:"required"` + Executed bool `json:"executed"` + Availability string `json:"availability"` + Compatibility string `json:"compatibility"` + Reachability string `json:"reachability"` + Policy string `json:"policy"` + ReasonCode string `json:"reasonCode"` + Candidates []ReportCandidate `json:"candidates"` +} + +// ReportCandidate intentionally has no observation or native identity input seam. +type ReportCandidate struct { + Component string `json:"component"` + SourceKind string `json:"sourceKind"` + OptionName string `json:"optionName,omitempty"` + LexicalPath string `json:"lexicalPath"` + ResolvedPath string `json:"resolvedPath"` + IsSymlink bool `json:"isSymlink,omitempty"` + Executed bool `json:"executed"` + Selected bool `json:"selected"` + Availability string `json:"availability"` + Compatibility string `json:"compatibility"` + ReasonCode string `json:"reasonCode"` + Detail string `json:"detail,omitempty"` +} + +// ReportAction describes the frozen action shape. Passive conversion emits none. +type ReportAction struct { + Kind string `json:"kind"` + Label string `json:"label"` + Enabled bool `json:"enabled"` + DisabledReasonCode string `json:"disabledReasonCode,omitempty"` + RequiresEffectAuthorization bool `json:"requiresEffectAuthorization"` + RequiresConfirmation bool `json:"requiresConfirmation"` + CLICommand string `json:"cliCommand,omitempty"` +} diff --git a/pkg/dependencies/report_validation_test.go b/pkg/dependencies/report_validation_test.go new file mode 100644 index 0000000000..0e93c5f3bd --- /dev/null +++ b/pkg/dependencies/report_validation_test.go @@ -0,0 +1,154 @@ +package dependencies + +import ( + "strings" + "time" +) + +func (s *reportSuite) TestForgedSurveyInputsRejected() { + mutations := map[string]func(*SurveyResult){ + "catalog ID": func(r *SurveyResult) { r.CatalogID = surveyUnknown }, + "catalog hash": func(r *SurveyResult) { r.CatalogHash = surveyUnknown }, + "unknown binding": func(r *SurveyResult) { r.BindingID = "custom" }, + "external binding": func(r *SurveyResult) { r.BindingID = "microsandbox" }, + "unverified": func(r *SurveyResult) { r.ContractVerified = false }, + "adapter": func(r *SurveyResult) { r.AdapterStatus = "forged_adapter_qualification" }, + "executed": func(r *SurveyResult) { r.Executed = true }, + "managed install": func(r *SurveyResult) { r.ManagedCapabilities.Install = true }, + "managed select": func(r *SurveyResult) { r.ManagedCapabilities.Select = true }, + "managed remove": func(r *SurveyResult) { r.ManagedCapabilities.Remove = true }, + "managed update": func(r *SurveyResult) { r.ManagedCapabilities.Update = true }, + "missing requirement": func(r *SurveyResult) { r.Requirements = nil }, + "duplicate requirement": func(r *SurveyResult) { r.Requirements = append(r.Requirements, r.Requirements[0]) }, + "tool": func(r *SurveyResult) { r.Requirements[0].Requirement.ToolID = reportPodman }, + "purpose": func(r *SurveyResult) { r.Requirements[0].Requirement.Purpose = reportTestOther }, + "scope": func(r *SurveyResult) { r.Requirements[0].Requirement.Scope = "guest" }, + "required for": func(r *SurveyResult) { r.Requirements[0].Requirement.RequiredFor[0] = reportTestOther }, + "executable option": func(r *SurveyResult) { r.Requirements[0].Requirement.ExecutableOption = "OTHER" }, + "configuration option": func(r *SurveyResult) { r.Requirements[0].Requirement.ConfigurationOption = "OTHER" }, + "probe ID": func(r *SurveyResult) { r.Requirements[0].Requirement.ProbeID = reportTestOther }, + "guidance": func(r *SurveyResult) { r.Requirements[0].Requirement.GuidanceID = reportTestOther }, + "backend": func(r *SurveyResult) { r.Requirements[0].Requirement.WhenImageBackend = reportTestOther }, + "policy reason": func(r *SurveyResult) { r.PolicyReason = reportTestUnreviewed }, + "item policy reason": func(r *SurveyResult) { r.Requirements[0].PolicyReason = reportTestUnreviewed }, + "item policy": func(r *SurveyResult) { r.Requirements[0].Policy = "managed_selected" }, + "item executed": func(r *SurveyResult) { r.Requirements[0].Executed = true }, + "compatible": func(r *SurveyResult) { r.Requirements[0].Compatibility = "compatible" }, + "incompatible": func(r *SurveyResult) { r.Requirements[0].Compatibility = "incompatible" }, + "reachability": func(r *SurveyResult) { r.Requirements[0].Reachability = "reachable" }, + "availability": func(r *SurveyResult) { r.Requirements[0].Availability = "available" }, + "reason": func(r *SurveyResult) { r.Requirements[0].ReasonCode = reportTestUnreviewed }, + } + for name, mutate := range mutations { + s.Run(name, func() { + result := s.result("docker") + mutate(&result) + s.reject(result, reportMetadata()) + }) + } + for _, catalog := range []*Catalog{nil, {}, {hash: "fabricated"}} { + report, err := catalog.FormatPassiveReport(s.result("docker"), reportMetadata()) + s.EqualError(err, reportInvalid) + s.Equal(Report{}, report) + } +} + +func (s *reportSuite) reject(result SurveyResult, metadata PassiveReportMetadata) { + report, err := s.catalog.FormatPassiveReport(result, metadata) + s.EqualError(err, reportInvalid) + s.Equal(Report{}, report) +} + +func (s *reportSuite) TestMalformedCandidateInputsRejected() { + for name, mutate := range map[string]func(*ExecutableCandidate){ + "executed": func(c *ExecutableCandidate) { c.Executed = true }, + "unknown state": func(c *ExecutableCandidate) { c.State = surveyUnknown }, + "unknown origin": func(c *ExecutableCandidate) { c.Origin = "managed_store" }, + "arbitrary reason": func(c *ExecutableCandidate) { c.ReasonCode = "private-fragment" }, + "version reason": func(c *ExecutableCandidate) { c.ReasonCode = surveyVersionUnknown }, + } { + s.Run(name, func() { + result := s.result("docker") + candidate := ExecutableCandidate{ + Origin: LookupPATH, + State: FileMissing, + LexicalPath: reportTestPath, + } + mutate(&candidate) + result.Requirements[0].Candidates = []ExecutableCandidate{candidate} + s.reject(result, reportMetadata()) + }) + } + result := s.result("docker") + result.Requirements[0].Candidates = []ExecutableCandidate{ + {Origin: LookupExplicit, State: FileMissing, LexicalPath: reportTestPath}, + {Origin: LookupPATH, State: FileMissing, LexicalPath: "/fallback/docker"}, + } + s.reject(result, reportMetadata()) + result = s.result(reportKubernetes) + result.Requirements[0].Candidates = []ExecutableCandidate{ + {Origin: LookupPATH, State: FileMissing}, + } + s.reject(result, reportMetadata()) +} + +func (s *reportSuite) TestRequiredMetadataAndHostFactsRejected() { + for name, mutate := range map[string]func(*SurveyResult){ + "context identity": func(r *SurveyResult) { r.Target.ContextName = "" }, + "provider identity": func(r *SurveyResult) { r.Target.ProviderName = "" }, + "config revision": func(r *SurveyResult) { r.Target.ConfigRevision = "" }, + "provider revision": func(r *SurveyResult) { r.Target.ProviderConfigRevision = "" }, + "empty OS": func(r *SurveyResult) { r.Host.GOOS = "" }, + "unknown OS": func(r *SurveyResult) { r.Host.GOOS = "freebsd" }, + "empty architecture": func(r *SurveyResult) { r.Host.GOARCH = "" }, + "unknown architecture": func(r *SurveyResult) { r.Host.GOARCH = "386" }, + "conflicting virtualization": func(r *SurveyResult) { r.Host.VirtualizationCapability = "kvm_available" }, + } { + s.Run(name, func() { + result := s.result("docker") + mutate(&result) + s.reject(result, reportMetadata()) + }) + } + for name, mutate := range map[string]func(*PassiveReportMetadata){ + "time": func(m *PassiveReportMetadata) { m.EvaluatedAt = time.Time{} }, + "invalid RFC3339 year": func(m *PassiveReportMetadata) { + m.EvaluatedAt = time.Date(10000, time.January, 1, 0, 0, 0, 0, time.UTC) + }, + "redactor": func(m *PassiveReportMetadata) { m.Redact = nil }, + "virtualization": func(m *PassiveReportMetadata) { m.VirtualizationCapability = "" }, + "unknown virtualization": func(m *PassiveReportMetadata) { m.VirtualizationCapability = surveyUnknown }, + "unsafe OS version": func(m *PassiveReportMetadata) { m.OSVersion = "secret\nversion" }, + } { + s.Run(name, func() { + metadata := reportMetadata() + mutate(&metadata) + s.reject(s.result("docker"), metadata) + }) + } +} + +func (s *reportSuite) TestUnsafeIdentitiesAreRejectedWithoutRepair() { + for _, value := range []string{ + " ", "name\nsecret", "https://host/provider", "file:/provider", "user:password@host", strings.Repeat("x", 4097), + "private-fragment", "provider\u202e", string([]byte{0xff}), + } { + for _, field := range []string{"context", "provider", "config", "providerConfig", "osVersion"} { + result, metadata := s.result("docker"), reportMetadata() + metadata.Redact = func(value string) string { return strings.ReplaceAll(value, "private-fragment", "") } + switch field { + case "context": + result.Target.ContextName = value + case "provider": + result.Target.ProviderName = value + case "config": + result.Target.ConfigRevision = value + case "providerConfig": + result.Target.ProviderConfigRevision = value + case "osVersion": + metadata.OSVersion = value + } + s.reject(result, metadata) + } + } +} diff --git a/pkg/dependencies/survey.go b/pkg/dependencies/survey.go new file mode 100644 index 0000000000..2f29ded661 --- /dev/null +++ b/pkg/dependencies/survey.go @@ -0,0 +1,222 @@ +package dependencies + +import ( + "context" + "errors" + "path/filepath" + "runtime" + "slices" + "strings" +) + +const ( + surveyUnknown = "unknown" + surveyMissing = "missing" + surveyAvailable = "available" + surveyIncomplete = "incomplete" + surveyNotChecked = "not_checked" + surveyExternalOnly = "external_only" + surveyPolicyBlocked = "dependency_policy_blocked" + surveyVersionUnknown = "dependency_version_unknown" + surveyUnsupported = "unsupported" + surveyPlatformUnsupported = "dependency_platform_unsupported" +) + +// Survey matches the trusted contract and observes its executable requirements +// through the supplied native lookup snapshot. It never executes, selects, +// installs, reads runtime configuration files, or checks an endpoint. Any error, +// including cancellation, discards the whole result. +func (c *Catalog) Survey(ctx context.Context, request SurveyRequest) (SurveyResult, error) { + if err := ctx.Err(); err != nil { + return SurveyResult{}, err + } + if err := validateSurvey(c, request); err != nil { + return SurveyResult{}, err + } + match, err := c.Match(request.Contract) + if err != nil { + // Catalog validation errors can contain caller-supplied contract values. + return SurveyResult{}, errors.New("invalid survey provider contract") + } + result := SurveyResult{ + Target: request.Target, Host: request.Host, + CatalogID: c.ID(), CatalogHash: c.Hash(), BindingID: match.BindingID, + ContractVerified: match.ContractVerified, AdapterStatus: match.AdapterStatus, + PolicyReason: c.surveyPolicyReason(match, runtime.GOOS+"/"+runtime.GOARCH), + } + for _, requirement := range match.Requirements { + item, err := surveyRequirement(ctx, request, requirement) + if err != nil { + return SurveyResult{}, err + } + item.PolicyReason = result.PolicyReason + if item.PolicyReason == surveyPlatformUnsupported { + item.Policy = surveyUnsupported + } + result.Requirements = append(result.Requirements, item) + } + if err := ctx.Err(); err != nil { + return SurveyResult{}, err + } + return result, nil +} + +func (c *Catalog) surveyPolicyReason(match ContractMatch, platform string) string { + if !match.ContractVerified { + return match.ManagedReason + } + for _, binding := range c.document.Bindings { + if binding.ID == match.BindingID && !slices.Contains(binding.Platforms, platform) { + return surveyPlatformUnsupported + } + } + return match.ManagedReason +} + +func validateSurvey(c *Catalog, request SurveyRequest) error { + if c == nil || c.hash == "" { + return errors.New("survey requires a loaded catalog") + } + if !filepath.IsAbs(request.Environment.cwd) { + return errors.New("survey requires an environment snapshot") + } + if request.Host.GOOS != "" && request.Host.GOOS != runtime.GOOS { + return errors.New("survey cannot inspect a different operating system") + } + if request.Host.GOARCH != "" && request.Host.GOARCH != runtime.GOARCH { + return errors.New("survey cannot inspect a different process architecture") + } + return nil +} + +func surveyRequirement( + ctx context.Context, + request SurveyRequest, + requirement Requirement, +) (RequirementSurvey, error) { + item := RequirementSurvey{ + Requirement: requirement, Availability: surveyUnknown, + Compatibility: surveyUnknown, Reachability: surveyNotChecked, + Policy: surveyExternalOnly, ReasonCode: surveyPolicyBlocked, + } + if requirement.ConfigurationOption != "" { + // Configuration guidance never parses kubeconfig or invokes exec auth. + return item, nil + } + lookup, err := surveyLookupRequest(request, requirement) + if err != nil { + return RequirementSurvey{}, err + } + var observed LookupResult + if surveyURI(lookup.Command) { + observed.ReasonCode = LookupInvalidPath + } else { + observed, err = request.Environment.LookupExecutable(ctx, lookup) + if err != nil { + return RequirementSurvey{}, err + } + } + item.Candidates = observed.Candidates + item.Availability = surveyAvailability(observed) + item.ReasonCode = surveyObservationReason(observed.ReasonCode, item.Availability) + for i := range item.Candidates { + if item.Candidates[i].ReasonCode == LookupInspectionDeferred { + item.Candidates[i].ReasonCode = surveyPolicyBlocked + } + } + return item, nil +} + +func surveyURI(command string) bool { + prefix, _, found := strings.Cut(command, "://") + // Native absolute and relative invocation paths retain their exact spelling. + return found && !filepath.IsAbs(command) && !invocationPath(prefix) +} + +func surveyLookupRequest(request SurveyRequest, requirement Requirement) (LookupRequest, error) { + command, ok := surveyDefaultCommand(requirement.ToolID) + if !ok { + return LookupRequest{}, errors.New("survey requirement has no reviewed executable") + } + lookup := LookupRequest{ + Command: command, + ReviewedLocations: slices.Clone(request.ReviewedLocations[requirement.ToolID]), + } + option, present := request.Options[requirement.ExecutableOption] + if requirement.ExecutableOption == "" || !present { + return lookup, nil + } + return applySurveyOption(lookup, option) +} + +func applySurveyOption(lookup LookupRequest, option SurveyOption) (LookupRequest, error) { + origin, err := surveyOptionOrigin(option) + if err != nil { + return LookupRequest{}, err + } + // Non-default static values are fixed choices too, even if inherited without + // UserProvided. Empty values must never become permission to search elsewhere. + lookup.Explicit = origin != SurveyDefault || option.UserProvided || + option.Value != lookup.Command + lookup.Command = option.Value + if lookup.Explicit { + lookup.ExplicitOrigin = LookupExplicit + if origin == LookupExplicitEnv { + lookup.ExplicitOrigin = origin + } + } + return lookup, nil +} + +func surveyOptionOrigin(option SurveyOption) (LookupOrigin, error) { + switch option.Origin { + case "", SurveyDefault: + return SurveyDefault, nil + case LookupExplicit, LookupExplicitEnv: + return option.Origin, nil + default: + return "", errors.New("invalid survey executable option origin") + } +} + +func surveyDefaultCommand(toolID string) (string, bool) { + // These identities are validated by the embedded catalog, not provider YAML. + switch toolID { + case toolDocker, "podman": + return toolID, true + case "apple-container": + return "container", true + case toolMicrosandbox: + return "msb", true + case toolLima: + return "limactl", true + case toolOrbStack: + return "orbctl", true + default: + return "", false + } +} + +func surveyObservationReason(reason, availability string) string { + switch reason { + case "": + return surveyVersionUnknown + case LookupInspectionDeferred: + return surveyPolicyBlocked + case LookupMissing: + return surveyUnavailableReason(availability) + default: + return reason + } +} + +func surveyUnavailableReason(availability string) string { + switch availability { + case surveyIncomplete: + return "dependency_incomplete" + case surveyUnknown: + return surveyPolicyBlocked + default: + return LookupMissing + } +} diff --git a/pkg/dependencies/survey_availability.go b/pkg/dependencies/survey_availability.go new file mode 100644 index 0000000000..0cf712df9f --- /dev/null +++ b/pkg/dependencies/survey_availability.go @@ -0,0 +1,31 @@ +package dependencies + +func surveyAvailability(observed LookupResult) string { + availability := surveyMissing + if observed.ReasonCode == LookupInvalidPath && len(observed.Candidates) == 0 { + availability = surveyUnknown + } + for _, candidate := range observed.Candidates { + state := surveyFileAvailability(candidate.State) + if state == surveyAvailable { + return state + } + if state == surveyUnknown || availability == surveyMissing { + availability = state + } + } + return availability +} + +func surveyFileAvailability(state FileState) string { + switch state { + case FileExecutable: + return surveyAvailable + case FileMissing: + return surveyMissing + case FileBrokenLink, FileNonregular, FileNonexecutable: + return surveyIncomplete + default: + return surveyUnknown + } +} diff --git a/pkg/dependencies/survey_safety_test.go b/pkg/dependencies/survey_safety_test.go new file mode 100644 index 0000000000..ba867094f0 --- /dev/null +++ b/pkg/dependencies/survey_safety_test.go @@ -0,0 +1,242 @@ +package dependencies + +import ( + "context" + "encoding/json" + "go/parser" + "go/token" + "io/fs" + "os" + "path/filepath" + "runtime" + "strconv" + "strings" + "testing" + "time" + + "github.com/devsy-org/devsy/internal/dependencytest" + "github.com/stretchr/testify/require" +) + +func (s *surveySuite) TestURIOptionsAreRejectedBeforeInspection() { + for _, value := range []string{ + "https://user:" + surveyTestSecret + "@host/docker", + "ssh://user:" + surveyTestSecret + "@host/docker", + "file://user:" + surveyTestSecret + "@host/docker", + } { + request := s.request("docker", "") + request.Options[surveyTestOption] = SurveyOption{Value: value, UserProvided: true} + request.Environment.inspect = func(context.Context, string) (lookupFile, error) { + s.FailNow("URI input must not reach filesystem metadata") + return lookupFile{}, nil + } + dependencytest.Preserve(s.T(), s.root) + result := s.survey(request) + item := result.Requirements[0] + s.Equal(LookupInvalidPath, item.ReasonCode) + s.Equal(surveyUnknown, item.Availability) + s.Empty(item.Candidates) + encoded, err := json.Marshal(result) + s.Require().NoError(err) + s.NotContains(string(encoded), surveyTestSecret) + } +} + +func (s *surveySuite) TestDeferredExplicitAndShimNeverFallback() { + fallback := s.executable("fallback/docker") + shim := s.executable("home/.local/share/mise/shims/docker") + for _, deferred := range []bool{false, true} { + request := s.request( + "docker", + filepath.Dir(shim)+string(filepath.ListSeparator)+filepath.Dir(fallback), + ) + request.Options[surveyTestOption] = SurveyOption{Value: toolDocker, UserProvided: true} + request.ReviewedLocations[toolDocker] = []string{fallback} + if deferred { + request.Environment.inspect = func(ctx context.Context, path string) (lookupFile, error) { + if path == shim { + return lookupFile{}, errLookupDeferred + } + return inspectLookupFile(ctx, path) + } + } + dependencytest.Preserve(s.T(), s.root) + item := s.survey(request).Requirements[0] + s.Require().Len(item.Candidates, 1) + candidate := item.Candidates[0] + s.Equal(shim, candidate.LexicalPath) + s.Nil(candidate.Identity) + if deferred { + s.Equal(surveyUnknown, item.Availability) + s.Equal(surveyPolicyBlocked, item.ReasonCode) + s.Equal(surveyPolicyBlocked, candidate.ReasonCode) + s.Equal(FileDeferred, candidate.State) + s.Empty(candidate.ResolvedPath) + } else { + s.Equal(surveyAvailable, item.Availability) + s.Equal(LookupIndirectLauncher, item.ReasonCode) + s.True(candidate.Launcher) + } + } +} + +func (s *surveySuite) TestFileStatesRemainDistinct() { + if runtime.GOOS == lookupWindows { + s.T().Skip("Unix execute bits and symlinks; native Windows safety is covered separately") + } + plain := filepath.Join(s.root, "plain") + s.Require().NoError(os.WriteFile(plain, []byte("not executable"), 0o600)) + directory := filepath.Join(s.root, "directory") + s.Require().NoError(os.Mkdir(directory, 0o700)) + missing := filepath.Join(s.root, "missing") + broken := filepath.Join(s.root, "broken") + s.Require().NoError(os.Symlink(missing, broken)) + for _, test := range []struct { + path string + state FileState + availability string + }{ + {plain, FileNonexecutable, surveyIncomplete}, + {directory, FileNonregular, surveyIncomplete}, + {missing, FileMissing, surveyMissing}, + {broken, FileBrokenLink, surveyIncomplete}, + } { + request := s.request("docker", "") + request.Options[surveyTestOption] = SurveyOption{Value: test.path, UserProvided: true} + item := s.survey(request).Requirements[0] + s.Equal(LookupInvalidPath, item.ReasonCode) + s.Equal(test.availability, item.Availability) + s.Require().Len(item.Candidates, 1) + s.Equal(test.state, item.Candidates[0].State) + } +} + +func (s *surveySuite) TestCanceledAndDeadlineReturnNoPartialResult() { + for _, cause := range []error{context.Canceled, context.DeadlineExceeded} { + request := s.externalRequest(toolMicrosandbox, executionMicrosandbox) + path := s.executable("tools/msb") + var err error + request.Environment, err = NewLookupEnvironment( + map[string]string{surveyTestPATH: filepath.Dir(path)}, + s.root, + ) + s.Require().NoError(err) + request.Environment.inspect = func(ctx context.Context, path string) (lookupFile, error) { + if strings.EqualFold(filepath.Base(path), "docker") || + strings.EqualFold(filepath.Base(path), "docker.exe") { + return lookupFile{}, cause + } + return inspectLookupFile(ctx, path) + } + result, err := s.catalog.Survey(context.Background(), request) + s.ErrorIs(err, cause) + s.Equal(SurveyResult{}, result) + } + canceled, cancel := context.WithCancel(context.Background()) + cancel() + deadline, expire := context.WithDeadline(context.Background(), time.Now().Add(-time.Second)) + defer expire() + for _, ctx := range []context.Context{canceled, deadline} { + result, err := s.catalog.Survey(ctx, s.request("docker", "")) + s.ErrorIs(err, ctx.Err()) + s.Equal(SurveyResult{}, result) + } +} + +func (s *surveySuite) TestAutomaticUnusableAndInaccessibleAreNotMissing() { + if runtime.GOOS == lookupWindows { + s.T().Skip("Unix execute-bit observation") + } + path := s.executable("tools/docker") + s.Require().NoError(os.Chmod(path, 0o600)) + request := s.request("docker", filepath.Dir(path)) + item := s.survey(request).Requirements[0] + s.Equal(surveyIncomplete, item.Availability) + s.Equal("dependency_incomplete", item.ReasonCode) + s.Require().Len(item.Candidates, 1) + s.Equal(FileNonexecutable, item.Candidates[0].State) + request.Environment.inspect = func(ctx context.Context, inspected string) (lookupFile, error) { + if inspected == path { + return lookupFile{}, fs.ErrPermission + } + return inspectLookupFile(ctx, inspected) + } + item = s.survey(request).Requirements[0] + s.Equal(surveyUnknown, item.Availability) + s.Equal(surveyPolicyBlocked, item.ReasonCode) + s.Require().Len(item.Candidates, 1) + s.Equal(FileInaccessible, item.Candidates[0].State) +} + +func (s *surveySuite) TestContextCancellationDuringInspectionDiscardsEvidence() { + path := s.executable("tools/docker") + request := s.request("docker", filepath.Dir(path)) + ctx, cancel := context.WithCancel(context.Background()) + defer cancel() + request.Environment.inspect = func(ctx context.Context, path string) (lookupFile, error) { + observed, err := inspectLookupFile(ctx, path) + cancel() + return observed, err + } + result, err := s.catalog.Survey(ctx, request) + s.ErrorIs(err, context.Canceled) + s.Equal(SurveyResult{}, result) +} + +func (s *surveySuite) TestInvalidInputsDoNotEchoValues() { + for _, mutate := range []func(*SurveyRequest){ + func(r *SurveyRequest) { r.Contract.AdapterVersion = surveyTestSecret }, + func(r *SurveyRequest) { r.Contract.ManifestSHA256 = surveyTestSecret }, + func(r *SurveyRequest) { r.Options[surveyTestOption] = SurveyOption{Origin: surveyTestSecret} }, + func(r *SurveyRequest) { r.Environment = LookupEnvironment{} }, + func(r *SurveyRequest) { r.Host.GOOS = surveyTestSecret }, + func(r *SurveyRequest) { r.Host.GOARCH = surveyTestSecret }, + } { + request := s.request("docker", "") + mutate(&request) + result, err := s.catalog.Survey(context.Background(), request) + s.Require().Error(err) + s.NotContains(err.Error(), surveyTestSecret) + s.Equal(SurveyResult{}, result) + } + var unloaded *Catalog + result, err := unloaded.Survey(context.Background(), s.request("docker", "")) + s.Error(err) + s.Equal(SurveyResult{}, result) +} + +func (s *surveySuite) TestCWDAndAmbientEnvironmentAreExcluded() { + cwd := s.executable("docker") + ambient := s.executable("ambient/docker") + s.T().Setenv(surveyTestPATH, filepath.Dir(ambient)) + request := s.request("docker", "."+string(filepath.ListSeparator)+filepath.Dir(cwd)) + dependencytest.Preserve(s.T(), s.root) + item := s.survey(request).Requirements[0] + s.Equal(surveyMissing, item.Availability) + s.Empty(item.Candidates) +} + +func TestSurveyHasNoEffectfulImports(t *testing.T) { + files, err := filepath.Glob("survey*.go") + require.NoError(t, err) + require.NotEmpty(t, files) + for _, path := range files { + if strings.HasSuffix(path, "_test.go") { + continue + } + file, err := parser.ParseFile(token.NewFileSet(), path, nil, parser.ImportsOnly) + require.NoError(t, err) + for _, imported := range file.Imports { + name, err := strconv.Unquote(imported.Path.Value) + require.NoError(t, err) + for _, forbidden := range []string{ + "os/exec", "net", "github.com/devsy-org/devsy/pkg/workspace", + "github.com/devsy-org/devsy/pkg/driver", "github.com/devsy-org/devsy/pkg/provider", + "github.com/devsy-org/devsy/pkg/config", "github.com/devsy-org/devsy/cmd", + } { + require.NotEqual(t, forbidden, name, path) + require.False(t, strings.HasPrefix(name, forbidden+"/"), path) + } + } + } +} diff --git a/pkg/dependencies/survey_test.go b/pkg/dependencies/survey_test.go new file mode 100644 index 0000000000..f78a09ca06 --- /dev/null +++ b/pkg/dependencies/survey_test.go @@ -0,0 +1,469 @@ +package dependencies + +import ( + "context" + "encoding/json" + "os" + "path/filepath" + "runtime" + "slices" + "strings" + "testing" + + "github.com/devsy-org/devsy/internal/dependencytest" + "github.com/stretchr/testify/suite" +) + +const ( + surveyTestOption = "DOCKER_PATH" + surveyTestSecret = "private-credential-never-report" + surveyTestPATH = "PATH" + surveyTestEndpointOption = "DOCKER_HOST" +) + +type surveySuite struct { + suite.Suite + catalog *Catalog + root string +} + +func TestSurvey(t *testing.T) { suite.Run(t, new(surveySuite)) } + +func (s *surveySuite) SetupTest() { + s.root = s.T().TempDir() + var err error + s.catalog, err = LoadCatalog() + s.Require().NoError(err) +} + +func (s *surveySuite) TestFoundMissingAndPassivePreservation() { + path := s.executable("tools/docker") + request := s.request("docker", filepath.Dir(path)) + request.Options[surveyTestEndpointOption] = SurveyOption{ + Value: "ssh://user:" + surveyTestSecret + "@host", + } + request.Options["DOCKER_ELEVATION"] = SurveyOption{Value: "sudo"} + dependencytest.Preserve(s.T(), s.root) + result := s.survey(request) + s.Require().Len(result.Requirements, 1) + item := result.Requirements[0] + s.Equal(surveyAvailable, item.Availability) + s.Equal(surveyUnknown, item.Compatibility) + s.Equal(surveyNotChecked, item.Reachability) + s.Equal(surveyVersionUnknown, item.ReasonCode) + s.Equal(surveyExternalOnly, item.Policy) + s.Equal("dependency_recipe_unqualified", item.PolicyReason) + s.Require().Len(item.Candidates, 1) + s.Equal(path, item.Candidates[0].LexicalPath) + s.NotNil(item.Candidates[0].Identity) + s.False(item.Candidates[0].Executed) + s.False(item.Executed) + s.False(result.Executed) + s.Equal(SurveyManagedCapabilities{}, result.ManagedCapabilities) + s.Equal(SurveyHost{}, result.Host) + encoded, err := json.Marshal(result) + s.Require().NoError(err) + s.NotContains(string(encoded), surveyTestSecret) + s.NotContains(string(encoded), "fileIdentity") + s.NoFileExists(filepath.Join(s.root, "EXECUTED")) + missing := s.survey(s.request("docker", "")) + s.Equal(surveyMissing, missing.Requirements[0].Availability) + s.Equal(LookupMissing, missing.Requirements[0].ReasonCode) + s.Empty(missing.Requirements[0].Candidates) +} + +func (s *surveySuite) TestRecognizedSourcesAndNameSpoofs() { + for _, binding := range s.catalog.Bindings() { + request := s.request("docker", "") + request.Contract = ProviderContract{ + Source: binding.Source, + ExecutionContract: binding.ExecutionContract, + } + result := s.survey(request) + s.Equal(binding.ID, result.BindingID) + s.True(result.ContractVerified) + s.NotEmpty(result.Requirements) + s.Equal(SurveyManagedCapabilities{}, result.ManagedCapabilities) + request.Contract.ExecutionContract = "custom" + s.Empty(s.survey(request).Requirements) + } + for _, name := range []string{toolDocker, toolMicrosandbox} { + request := s.request("docker", "") + request.Contract = ProviderContract{ + DisplayName: name, + Source: ProviderSource{ + Kind: SourceURL, + Location: "https://user:" + surveyTestSecret + "@custom", + }, + ExecutionContract: executionDocker, + } + request.Environment.inspect = func(context.Context, string) (lookupFile, error) { + s.FailNow("untrusted source must not inspect files") + return lookupFile{}, nil + } + result := s.survey(request) + s.Empty(result.Requirements) + s.False(result.ContractVerified) + s.Equal(surveyPolicyBlocked, result.PolicyReason) + encoded, err := json.Marshal(result) + s.Require().NoError(err) + s.NotContains(string(encoded), surveyTestSecret) + } +} + +func (s *surveySuite) TestDefaultAndExplicitOptionIntent() { + first := s.executable("first/docker") + second := s.executable("second/docker") + reviewed := s.executable("reviewed/docker") + path := strings.Join( + []string{filepath.Dir(first), filepath.Dir(second)}, + string(filepath.ListSeparator), + ) + for _, option := range []SurveyOption{ + {Value: toolDocker, Origin: SurveyDefault}, + {Value: toolDocker, Origin: SurveyDefault, UserProvided: true}, + {Value: toolDocker, Origin: LookupExplicit}, + {Value: toolDocker, Origin: LookupExplicitEnv}, + } { + request := s.request("docker", path) + request.Options[surveyTestOption] = option + request.ReviewedLocations[toolDocker] = []string{reviewed} + item := s.survey(request).Requirements[0] + if option.Origin == SurveyDefault && !option.UserProvided { + s.Len(item.Candidates, 3) + s.Equal(LookupPATH, item.Candidates[0].Origin) + } else { + s.Require().Len(item.Candidates, 1) + origin := LookupExplicit + if option.Origin == LookupExplicitEnv { + origin = LookupExplicitEnv + } + s.Equal(origin, item.Candidates[0].Origin) + } + s.Equal(first, item.Candidates[0].LexicalPath) + } +} + +func (s *surveySuite) TestEmptyInvalidAndMissingExplicitNeverFallback() { + fallback := s.executable("fallback/docker") + values := []string{ + "", + "missing", + filepath.Join(s.root, "absent"), + "bad\x00path", + "https://" + surveyTestSecret + "@host", + } + for _, value := range values { + for _, origin := range []LookupOrigin{SurveyDefault, LookupExplicit, LookupExplicitEnv} { + request := s.request("docker", filepath.Dir(fallback)) + request.Options[surveyTestOption] = SurveyOption{Value: value, Origin: origin} + request.ReviewedLocations[toolDocker] = []string{fallback} + item := s.survey(request).Requirements[0] + s.Equal(LookupInvalidPath, item.ReasonCode) + for _, candidate := range item.Candidates { + s.NotEqual(fallback, candidate.LexicalPath) + s.NotContains(candidate.LexicalPath, surveyTestSecret) + } + } + } +} + +func (s *surveySuite) TestReviewedLocationsAndExactPaths() { + selected := s.executable(" spaced \u96ea/tools;literal ") + fallback := s.executable("fallback/docker") + request := s.request("docker", "") + request.ReviewedLocations[toolDocker] = []string{selected} + item := s.survey(request).Requirements[0] + s.Require().Len(item.Candidates, 1) + s.Equal(selected, item.Candidates[0].LexicalPath) + s.Equal(LookupReviewed, item.Candidates[0].Origin) + request = s.request("docker", filepath.Dir(fallback)) + request.Options[surveyTestOption] = SurveyOption{Value: selected, UserProvided: true} + request.ReviewedLocations[toolDocker] = []string{fallback} + item = s.survey(request).Requirements[0] + s.Require().Len(item.Candidates, 1) + s.Equal(selected, item.Candidates[0].LexicalPath) + s.Equal(LookupExplicit, item.Candidates[0].Origin) +} + +func (s *surveySuite) TestNativePathContainingURIDelimiter() { + if runtime.GOOS == lookupWindows { + s.T().Skip("Unix path with a colon directory") + } + path := s.executable("tools:/docker") + path = strings.Replace(path, "tools:/", "tools://", 1) + request := s.request("docker", "") + request.Options[surveyTestOption] = SurveyOption{Value: path, UserProvided: true} + dependencytest.Preserve(s.T(), s.root) + observed, err := request.Environment.LookupExecutable(context.Background(), LookupRequest{ + Command: path, Explicit: true, + }) + s.Require().NoError(err) + s.Require().Len(observed.Candidates, 1) + s.Equal(FileExecutable, observed.Candidates[0].State) + item := s.survey(request).Requirements[0] + s.Equal(surveyAvailable, item.Availability) + s.Equal(surveyVersionUnknown, item.ReasonCode) + s.Require().Len(item.Candidates, 1) + s.Equal(path, item.Candidates[0].LexicalPath) + s.True(observed.Candidates[0].Identity.SameFile(item.Candidates[0].Identity)) + s.NoFileExists(filepath.Join(s.root, "EXECUTED")) +} + +func (s *surveySuite) TestWindowsNativePathContainingURIDelimiter() { + if runtime.GOOS != lookupWindows { + s.T().Skip("requires native Windows drive path semantics") + } + path := filepath.ToSlash(s.executable("tools/docker")) + volume := filepath.VolumeName(path) + s.Require().NotEmpty(volume) + path = volume + "//" + strings.TrimPrefix(path, volume+"/") + request := s.request("docker", "") + request.Options[surveyTestOption] = SurveyOption{Value: path, UserProvided: true} + dependencytest.Preserve(s.T(), s.root) + observed, err := request.Environment.LookupExecutable(context.Background(), LookupRequest{ + Command: path, Explicit: true, + }) + s.Require().NoError(err) + s.Require().Len(observed.Candidates, 1) + s.Equal(FileExecutable, observed.Candidates[0].State) + item := s.survey(request).Requirements[0] + s.Equal(surveyAvailable, item.Availability) + s.Require().Len(item.Candidates, 1) + s.Equal(path, item.Candidates[0].LexicalPath) + s.True(observed.Candidates[0].Identity.SameFile(item.Candidates[0].Identity)) +} + +func (s *surveySuite) TestCatalogPlatformPolicySyntheticTuples() { + // Synthetic policy inputs exercise catalog exclusions, not native OS lookup. + for _, binding := range s.catalog.Bindings() { + match, err := s.catalog.Match(ProviderContract{ + Source: binding.Source, ExecutionContract: binding.ExecutionContract, + }) + s.Require().NoError(err) + for _, platform := range []string{ + "linux/amd64", "linux/arm64", "darwin/amd64", "darwin/arm64", + "windows/amd64", "windows/arm64", + } { + expected := "dependency_platform_unsupported" + if slices.Contains(binding.Platforms, platform) { + expected = match.ManagedReason + } + s.Equal( + expected, + s.catalog.surveyPolicyReason(match, platform), + binding.ID+" on "+platform, + ) + } + match.ContractVerified = false + match.ManagedReason = surveyPolicyBlocked + s.Equal(surveyPolicyBlocked, s.catalog.surveyPolicyReason(match, "other/unknown")) + } +} + +func (s *surveySuite) TestNativeCatalogPlatformPolicy() { + platform := runtime.GOOS + "/" + runtime.GOARCH + path := s.executable("native/tool") + dependencytest.Preserve(s.T(), s.root) + for _, binding := range s.catalog.Bindings() { + request := s.request("docker", "") + request.Contract = ProviderContract{ + Source: binding.Source, ExecutionContract: binding.ExecutionContract, + } + if binding.Requirements[0].ConfigurationOption == "" { + request.ReviewedLocations[binding.Requirements[0].ToolID] = []string{path} + } + before := s.survey(request) + request.Host = SurveyHost{GOOS: runtime.GOOS, GOARCH: runtime.GOARCH} + after := s.survey(request) + s.Equal(before.PolicyReason, after.PolicyReason) + s.Empty(after.Host.NativeArchitecture) + s.Empty(after.Host.VirtualizationCapability) + s.Equal(SurveyManagedCapabilities{}, after.ManagedCapabilities) + item := after.Requirements[0] + if binding.Requirements[0].ConfigurationOption == "" { + s.Equal(surveyAvailable, item.Availability) + } + if slices.Contains(binding.Platforms, platform) { + s.Equal("dependency_recipe_unqualified", after.PolicyReason) + s.Equal(surveyExternalOnly, item.Policy) + } else { + s.Equal("dependency_platform_unsupported", after.PolicyReason) + s.Equal(after.PolicyReason, item.PolicyReason) + s.Equal("unsupported", item.Policy) + } + } +} + +func (s *surveySuite) TestConditionalBackendAndGuestIsolation() { + msb := s.executable("runtime/msb") + for _, backend := range []string{"", toolDocker, imageBackendNone} { + request := s.externalRequest(toolMicrosandbox, "external_microsandbox_v1") + var err error + request.Environment, err = NewLookupEnvironment( + map[string]string{surveyTestPATH: filepath.Dir(msb)}, + s.root, + ) + s.Require().NoError(err) + request.Contract.ImageBackend = backend + request.Contract.AdapterVersion = "0.1.11" + request.Options["DockerPath"] = SurveyOption{Value: surveyTestSecret, UserProvided: true} + request.Options["MICROSANDBOX_PATH"] = SurveyOption{ + Value: surveyTestSecret, + UserProvided: true, + } + result := s.survey(request) + count := 2 + if backend == imageBackendNone { + count = 1 + } + s.Require().Len(result.Requirements, count) + s.Equal(toolMicrosandbox, result.Requirements[0].Requirement.ToolID) + s.Equal(surveyAvailable, result.Requirements[0].Availability) + s.Equal(surveyUnknown, result.Requirements[0].Compatibility) + s.Equal(surveyVersionUnknown, result.Requirements[0].ReasonCode) + s.Equal(SurveyManagedCapabilities{}, result.ManagedCapabilities) + s.Equal("version_unqualified", result.AdapterStatus) + if count == 2 { + s.Equal(toolDocker, result.Requirements[1].Requirement.ToolID) + s.Equal("image_backend", result.Requirements[1].Requirement.Purpose) + s.Empty(result.Requirements[1].Requirement.ExecutableOption) + } + } + for _, provider := range []string{toolLima, toolOrbStack} { + request := s.externalRequest(provider, provider+"_exec_v1") + request.Options[surveyTestOption] = SurveyOption{ + Value: surveyTestSecret, + UserProvided: true, + } + result := s.survey(request) + s.Require().Len(result.Requirements, 1) + s.Equal(provider, result.Requirements[0].Requirement.ToolID) + s.Equal("controller_host", result.Requirements[0].Requirement.Scope) + } +} + +func (s *surveySuite) TestKubernetesConfigurationIsInert() { + credential := s.executable("credentials/credential-plugin") + request := s.request("kubernetes", filepath.Dir(credential)) + request.Options["KUBERNETES_CONFIG"] = SurveyOption{ + Value: "users:\n- user:\n exec:\n command: " + credential + "\n args: [" + surveyTestSecret + "]", + } + request.Environment.inspect = func(context.Context, string) (lookupFile, error) { + s.FailNow("configuration guidance must not look up files") + return lookupFile{}, nil + } + dependencytest.Preserve(s.T(), s.root) + result := s.survey(request) + s.Require().Len(result.Requirements, 1) + item := result.Requirements[0] + s.Equal("KUBERNETES_CONFIG", item.Requirement.ConfigurationOption) + s.Equal(surveyUnknown, item.Availability) + s.Equal(surveyPolicyBlocked, item.ReasonCode) + s.Equal(surveyNotChecked, item.Reachability) + s.Empty(item.Candidates) + s.NoFileExists(filepath.Join(s.root, "EXECUTED")) + encoded, err := json.Marshal(result) + s.Require().NoError(err) + s.NotContains(string(encoded), surveyTestSecret) + s.NotContains(string(encoded), credential) +} + +func (s *surveySuite) TestInputOutputAndRevisionIsolation() { + path := s.executable("reviewed/docker") + request := s.request("docker", "") + request.Target = SurveyTarget{ + StoreID: "store-1", + ContextName: "context-1", + ProviderName: "provider-1", + ProviderFingerprint: "fingerprint-1", + ConfigRevision: "config-1", + ProviderConfigRevision: "provider-config-1", + } + request.ReviewedLocations[toolDocker] = []string{path} + before := s.survey(request) + s.Equal(request.Target, before.Target) + s.Equal(s.catalog.ID(), before.CatalogID) + s.Equal(s.catalog.Hash(), before.CatalogHash) + before.Requirements[0].Requirement.RequiredFor[0] = "mutated-operation" + before.Requirements[0].Candidates[0].LexicalPath = "mutated-candidate-path" + after := s.survey(request) + s.Equal("create", after.Requirements[0].Requirement.RequiredFor[0]) + s.Equal(path, after.Requirements[0].Candidates[0].LexicalPath) + request.ReviewedLocations[toolDocker][0] = filepath.Join(s.root, "missing") + request.Target.ConfigRevision = "config-2" + request.Target.ProviderConfigRevision = "provider-config-2" + changed := s.survey(request) + s.NotEqual(after.Target, changed.Target) + s.Empty(changed.Requirements[0].Candidates) + s.Equal(path, after.Requirements[0].Candidates[0].LexicalPath) + s.Equal("config-1", after.Target.ConfigRevision) +} + +func (s *surveySuite) TestEffectiveEnvironmentSnapshotIsImmutable() { + path := s.executable("supplied/docker") + values := map[string]string{ + surveyTestPATH: filepath.Dir(path), + surveyTestEndpointOption: surveyTestSecret, + } + request := s.request("docker", "") + var err error + request.Environment, err = NewLookupEnvironment(values, s.root) + s.Require().NoError(err) + values[surveyTestPATH] = s.root + delete(values, surveyTestEndpointOption) + dependencytest.Preserve(s.T(), s.root) + result := s.survey(request) + s.Require().Len(result.Requirements[0].Candidates, 1) + s.Equal(path, result.Requirements[0].Candidates[0].LexicalPath) + encoded, err := json.Marshal(result) + s.Require().NoError(err) + s.NotContains(string(encoded), surveyTestSecret) +} + +func (s *surveySuite) request(provider, path string) SurveyRequest { + environment, err := NewLookupEnvironment(map[string]string{surveyTestPATH: path}, s.root) + s.Require().NoError(err) + return SurveyRequest{ + Contract: ProviderContract{ + Source: ProviderSource{Kind: SourceInternal, InternalID: provider}, + ExecutionContract: "internal_" + provider, + }, + Environment: environment, + Options: map[string]SurveyOption{}, + ReviewedLocations: map[string][]string{}, + } +} + +func (s *surveySuite) externalRequest(provider, contract string) SurveyRequest { + request := s.request("docker", "") + request.Contract = ProviderContract{ + Source: ProviderSource{ + Kind: SourceGitHub, + Repository: "github.com/devsy-org/devsy-provider-" + provider, + }, + ExecutionContract: contract, + } + return request +} + +func (s *surveySuite) survey(request SurveyRequest) SurveyResult { + result, err := s.catalog.Survey(context.Background(), request) + s.Require().NoError(err) + return result +} + +func (s *surveySuite) executable(relative string) string { + path := filepath.Join(s.root, relative) + if runtime.GOOS == lookupWindows { + path += ".EXE" + } + s.Require().NoError(os.MkdirAll(filepath.Dir(path), 0o700)) + marker := strings.ReplaceAll(filepath.Join(s.root, "EXECUTED"), "'", "'\\''") + s.Require(). + NoError(os.WriteFile(path, []byte("#!/bin/sh\nprintf executed > '"+marker+"'\n"), 0o600)) + info, err := os.Stat(path) + s.Require().NoError(err) + s.Require().NoError(os.Chmod(path, info.Mode()|0o100)) + return path +} diff --git a/pkg/dependencies/survey_types.go b/pkg/dependencies/survey_types.go new file mode 100644 index 0000000000..70cec6fc36 --- /dev/null +++ b/pkg/dependencies/survey_types.go @@ -0,0 +1,83 @@ +package dependencies + +// SurveyOption is an already-effective static executable option. Map presence +// distinguishes absent from empty. Origin is default, explicit_option, or +// explicit_env; an empty origin means default. UserProvided preserves explicit +// intent even when the value equals the reviewed default command. +type SurveyOption struct { + Value string + Origin LookupOrigin + UserProvided bool +} + +const SurveyDefault LookupOrigin = "default" + +// SurveyTarget contains opaque orchestration identities, never credentials or +// raw source URLs. Consumers must compare all identities before using a result. +type SurveyTarget struct { + StoreID string + ContextName string + ProviderName string + ProviderFingerprint string + ConfigRevision string + ProviderConfigRevision string +} + +// SurveyHost contains caller-observed facts. Empty fields remain unknown. +// GOOS and GOARCH describe the process performing lookup, not a remote host. +type SurveyHost struct { + GOOS string + GOARCH string + NativeArchitecture string + VirtualizationCapability string +} + +// SurveyRequest has no runner, dynamic option resolver, store, or active probe. +// Contract must be established by trusted orchestration; source names alone do +// not establish its assertions. Callers must not mutate inputs during Survey. +type SurveyRequest struct { + Target SurveyTarget + Host SurveyHost + Contract ProviderContract + Environment LookupEnvironment + Options map[string]SurveyOption + // ReviewedLocations contains complete trusted paths, keyed by matched ToolID. + // Entries for tools outside the matched requirements are ignored. + ReviewedLocations map[string][]string +} + +// SurveyResult is an internal passive observation, not the v1 CLI wire report. +// It contains no saved selection, pair certification, or execution authority. +type SurveyResult struct { + Target SurveyTarget + Host SurveyHost + CatalogID string + CatalogHash string + BindingID string + ContractVerified bool + AdapterStatus string + PolicyReason string + ManagedCapabilities SurveyManagedCapabilities + Requirements []RequirementSurvey + Executed bool +} + +// SurveyManagedCapabilities remains all false in passive Survey. +type SurveyManagedCapabilities struct { + Install bool + Select bool + Remove bool + Update bool +} + +type RequirementSurvey struct { + Requirement Requirement + Availability string + Compatibility string + Reachability string + Policy string + PolicyReason string + ReasonCode string + Candidates []ExecutableCandidate + Executed bool +} diff --git a/pkg/dependencies/testdata/contracts/BASELINE_AND_GUARD_MAP.md b/pkg/dependencies/testdata/contracts/BASELINE_AND_GUARD_MAP.md new file mode 100644 index 0000000000..77fbe6a536 --- /dev/null +++ b/pkg/dependencies/testdata/contracts/BASELINE_AND_GUARD_MAP.md @@ -0,0 +1,299 @@ +# Provider Dependencies T00a: Source Baseline, Contract Ledger, and T00b Guard Map + +Tracker: `devsy-org/devsy#1575` +Slice: **T00a** (baseline reconciliation, contract fixtures, and T00b guard implementation map; `T00` is not complete until `T00b` lands). +Authority order: `REVIEW_ADDENDUM.md` (overrides `SPEC.md`) -> `SPEC.md`. +Baseline observation snapshot: `2026-10-19T11:19:00Z` UTC at `devsy-org/devsy` worktree base `91c36557c17eebb7bc9c5773282664f143721c8a` and GitHub API audit (`source-audit-current.json`). Recorded commits and releases describe this exact baseline observation, not a permanently current claim. + +--- + +## 1. Pinned Source Head Reconciliation (SPEC.md Section 2.1 vs Observed Baseline Heads) + +| Repository | SPEC.md Section 2.1 Pinned Commit | Observed `main` Commit (at `2026-10-19T11:19:00Z`) | Latest Published Release (`tag` / target commit) | Drift Summary and Plan Impact | +| :--- | :--- | :--- | :--- | :--- | +| `devsy-org/devsy` | `61e6d1ab8db5c0c6fd8c43abeee85b1d931e7866` | `91c36557c17eebb7bc9c5773282664f143721c8a` (`2026-10-19T10:01:51Z`) | `v1.24.0` (`1f47cd185bd134b45cdce12b947f6c601d76d329`, published `2026-10-19T03:59:00Z`); prior prerelease `v1.24.0-beta.7` (`35dcc9afcd68cabc9cc1abbe23f2c334a15f935b`) | 25 commits ahead of pinned head (see Section 1.2). Status/error envelopes, config schema (`1`), lock files, provider downloader, and option resolution semantics are unchanged; recent commits updated provider delete/rename and workspace provider helpers (`Pro` -> `Platform` naming), Docker `EnsureImage` retry handling, and `pkg/task` dead-worker `flock` reconciliation. | +| `devsy-org/devsy-provider-microsandbox` | `12ea902204bc86f1153335613001232aca6b7b9d` | `12ea902204bc86f1153335613001232aca6b7b9d` (`2026-10-17T17:13:25Z`) | `v0.1.11` (`02f3104d72d05b9846f56fe520d2688460d75e8e`, published `2026-10-16T23:44:11Z`) | `main` is unchanged from SPEC.md Section 2.1 and is 2 non-code commits (`f7bac4c73ed03561c453e1d5364317e33b0265f8` docs, `12ea902204bc86f1153335613001232aca6b7b9d` mise/prek) ahead of `v0.1.11`. Neither `v0.1.11` nor `main` implements `T08` (see Section 1.1). Metadata/source inspection is not native qualification; all managed tuples remain disabled and `G01`-`G09` are `NOT RUN`. | +| `devsy-org/devsy-provider-lima` | `a0e05a9ba5f4e72f06a45d955dd7490b606eb759` | `5ce6fcc9dc3fa2bd92948ffb89a71e982498d2a3` (`2026-10-19T06:55:56Z`) | `v1.1.0` (`a0e05a9ba5f4e72f06a45d955dd7490b606eb759`, published `2026-07-25T16:23:40Z`) | 1 commit ahead of pinned head (`5ce6fcc9dc3fa2bd92948ffb89a71e982498d2a3` `go.mod`/`go.sum` devsy dependency update). `LIMA_PATH`, `LIMA_INSTANCE`, and `limactl` discovery seams match SPEC.md Section 2.3. | +| `devsy-org/devsy-provider-orbstack` | `3b26b06482a376b13fba4391498b958ffd6901e9` | `b3698a954b23a65d2be402c50f445aa33f1a8f5e` (`2026-10-19T10:12:09Z`) | `v1.1.4` (`aa2de43b31ebf491e1fb22dca1a2cf51b1ce3b23`, published `2026-10-19T05:48:11Z`) | 6 CI/dependency/release/tooling commits ahead of pinned head (`e8f76e044c968f3b8a810279430bf27afc1c7049` release workflow, `a26c136455dd2e073e8a8021b63c02af320dfd00` `go.mod` `devsy v1.24.0`, `aa2de43b31ebf491e1fb22dca1a2cf51b1ce3b23` release `1.1.4`, `7b6fc8a746804e1412d82b53dd826b9cebceb9b3` `prek-action`, `d842683cfba4d7909086a850970361425bfcdf02` `mise`/`prek` migration, `b3698a954b23a65d2be402c50f445aa33f1a8f5e` `prek v0.5.6`). Only `.github/workflows/`, `go.mod`/`go.sum`, `CHANGELOG.md`, `.release-please-manifest.json`, and `mise`/`prek` config files changed; `ORBSTACK_PATH` and `/Applications/OrbStack.app/Contents/MacOS/bin/orbctl` runtime seams are unchanged. | +| `devsy-org/devsy-runtime-sdk` | `9b7f92bda5965bc8a93166d4716745940c32cf17` | `9b7f92bda5965bc8a93166d4716745940c32cf17` (`2026-10-17T17:24:42Z`) | `v1.6.0` (`66d0b994e9433c9e89bcdbea80fe9dba99f5cede`, published `2026-10-11T18:16:57Z`) | Unchanged (`ProtocolVersion = "1.0"`, `Serve`, `Capabilities`, `Requirements` unchanged). | + +### 1.1 Published `devsy-provider-microsandbox` `v0.1.11` Metadata and Independent Verification + +- **Release tag**: `v0.1.11` (`https://github.com/devsy-org/devsy-provider-microsandbox/releases/tag/v0.1.11`) +- **Target commit**: `02f3104d72d05b9846f56fe520d2688460d75e8e` (`published_at: 2026-10-16T23:44:11Z`) +- **Published release asset digests**: + - `provider.yaml` (`4025` bytes): `sha256:2d33a4c2215dd11530e61ed2883e1bda0e8f117a3f8a112900f5e019d8caf5fa` + - `checksums.txt` (`427` bytes): `sha256:e094b426f41530af126be18dbeb791bfd77a6e529b3a4372d77c2f844acf941a` + - `devsy-runtime-microsandbox-linux-amd64` (`57683272` bytes): `sha256:8a0bc73aea4fe22b645c003700c2b9ae7ba1b7df64cfba6c2ea9142e2766ef66` + - `devsy-runtime-microsandbox-linux-arm64` (`50178752` bytes): `sha256:b0562724b125a65344e0b0e43ff6ea955e0ef42afe23b600a654128221ef9e0a` + - `devsy-runtime-microsandbox-darwin-arm64` (`48455746` bytes): `sha256:8aced83516ca045749ad0050d36d02ce9a0c7a308e4b310625448423e880e80c` + - `devsy-runtime-microsandbox-windows-amd64.exe` (`62390676` bytes): `sha256:ef109903146ea4fa0f3486829bb181c91cd3b39999df15f94ca885567fbd8fab` + - `LICENSE` (`16726` bytes): `sha256:3f3d9e0024b1921b067d6f7f88deb4a60cbe7a78e76c64e3f1d7fc3b779b9d04` + - `MICROSANDBOX-SDK-LICENSE` (`11324` bytes): `sha256:a276ca3381fefb9cde42fccae847856085c76027557d62eee83f057eb6c53433` +- **Verification of `v0.1.11` (`02f3104d72d05b9846f56fe520d2688460d75e8e`) and `main` (`12ea902204bc86f1153335613001232aca6b7b9d`)**: + 1. The generated manifest template declares MicroSandbox resource/runtime options (including `MICROSANDBOX_MEMORY` and `MICROSANDBOX_CPUS`); `MICROSANDBOX_PATH` and `MICROSANDBOX_LIBKRUNFW_PATH` do not exist yet. + 2. `cmd/devsy-runtime-microsandbox/main.go` accepts only `--version` or `serve`; `runtime-check --json` does not exist yet. + 3. `internal/msb/guest_exec.go` invokes `microsandbox.GetSandbox(ctx, name)` without setting `MSB_PATH` or `MSB_LIBKRUNFW_PATH`, and `internal/msb/cli.go` resolves `msb` via `c.MSBPath`, `exec.LookPath("msb")`, `~/.local/bin/msb`, or `~/.microsandbox/bin/msb`. + 4. **Conclusion**: `v0.1.11` is not eligible for managed activation (`G01` is `NOT RUN`). Source/release metadata inspection does not constitute native qualification; all managed tuples remain disabled and no synthetic future tag may be claimed as released support. + +### 1.2 `devsy-org/devsy` Drift Between `61e6d1ab8db5c0c6fd8c43abeee85b1d931e7866` and `91c36557c17eebb7bc9c5773282664f143721c8a` (25 Commits) + +1. **Provider delete/rename and workspace provider mutation helpers** (`91c36557c17eebb7bc9c5773282664f143721c8a`, PR #1580; `e4f8e8ec0868f7c583de675287325b52c21bafc2`, PR #1556): + - Renamed `pkg/workspace/pro.go` -> `pkg/workspace/platform.go` (`ListProInstances` -> `ListPlatformInstances` at line 11, `FindProviderProInstance` -> `FindProviderPlatformInstance` at line 41) and updated callers in `cmd/provider/delete.go` (`DeleteProvider` at line 97, calling `workspace.ListPlatformInstances` at line 106), `cmd/provider/rename.go` (`validateProviderRename` at line 239, calling `workspace.ListPlatformInstances` at line 250), `pkg/workspace/provider.go` (`ProviderFromHost` at line 108), `pkg/workspace/provider_update.go` (`CheckProviderUpdate` at line 18, `checkProviderUpdateForInstance` at line 35, `GetProInstance` at line 161), and `pkg/workspace/rename.go` (`Rename` at line 193). + - Stabilized Windows provider update tests in `pkg/workspace/provider_update_{extended,prepared,preservation}_test.go` (`e4f8e8ec0868f7c583de675287325b52c21bafc2`). + - Provider operation locking (`LockProvider` / `LockProviderNamed`) and config mutation boundaries in `cmd/provider/{add,init,set,set_source,delete,rename,use}.go` and `pkg/workspace/provider.go` (`AddProvider`, `UpdateProvider`, `CloneProvider`, `SwitchProvider`) remain unchanged and must be integrated with `T07` reference scanning. +2. **Task / worker job ownership and held-`flock` reconciliation** (`70c4914168bcc97243cdd1487a01aee9639e0329`, PR #1576): + - Added `(*State).NeedsReconciliation()` (`pkg/task/task.go:139`) and extracted `(*Store).tryLock` (`pkg/task/store.go:499`) shared by `tryWorkerLock` (`pkg/task/store.go:491`) and `tryLauncherLock` (`pkg/task/store.go:495`), alongside `claimDeadWorkerLock` (`pkg/task/store.go:520`). + - This reinforces core's held-`flock` liveness pattern (`HoldWorkerLock` at `pkg/task/task.go:208` vs nonblocking `TryLock()` during `ReconcileTask`/`ReconcileState` at `pkg/task/store.go:140, 165`), matching `REVIEW_ADDENDUM.md` Section 2 for planned `T07` dependency operation (`locks/operations/.lock`) and launch lease (`locks/leases/.lock`) liveness. +3. **Docker lifecycle and Podman CI** (`99c6ad0b93ddc0250c5b2c32e0db2bd9654692b0`, PR #1573; `1f47cd185bd134b45cdce12b947f6c601d76d329`, PR #1557): + - Updated `(*dockerDriver).EnsureImage` (`pkg/driver/docker/lifecycle.go:340`), `inspectImage` (line 373), and `waitForLocalImage` (line 384) for deterministic local image retry testing (`99c6ad0b93ddc0250c5b2c32e0db2bd9654692b0`), and bounded Windows Podman CI startup (`1f47cd185bd134b45cdce12b947f6c601d76d329`, tagged `v1.24.0`). + - `NewDockerDriver` (`pkg/driver/docker/docker.go:39`, calling `dockerHelper.EnsureElevated()` at line 82) and `(*dockerDriver).Preflight` (`pkg/driver/docker/docker.go:116`, calling `runPreflight` at line 193 -> `recoverPodman` at line 303) are unchanged. +4. **Desktop `ProviderWizard.svelte`** (`35dcc9afcd68cabc9cc1abbe23f2c334a15f935b`, PR #1562, tagged `v1.24.0-beta.7`): + - Added `footerPrimaryButtonClass` at line 112 and applied it to footer buttons (lines 844, 848, 864). + - Zero-visible-option skip (`if (visibleOptions.length === 0) { currentStep = "initialize"; void startInit(operationSession) }`) remains at lines 366-369 (`handleSelect`) and 408-413 (`handleConfigure`). +5. **CLI/Platform environment and naming** (`d8056aff105702b6698c64d79cd940e3230a7500`, PR #1568; `0dadc018479421bca22271276dfb27803c2211df`, PR #1561; `30ba4a91758efcc04bbb3cd98bab34121d2a2431`, PR #1571): + - Renamed `EnvLoftProject` -> `EnvProject` (`DEVSY_PROJECT`) and `EnvLoftFilterByOwner` -> `EnvFilterByOwner` (`DEVSY_FILTER_BY_OWNER`) in `pkg/config/env.go`, `pkg/provider/env.go`, and `pkg/workspace/list.go`, and updated platform instance naming in `pkg/platform/` and `pkg/daemon/platform/`. +6. **MicroSandbox CI policy wrapper** (`b418898e471e01fd15aee7559355d16be221c0d5`, PR #1559): + - Replaced `hack/run-managed-policy-e2e.sh` with `hack/microsandbox/managed_policy_{linux,other,test}.go`. + - `hack/microsandbox/install.go` is unchanged (`v0.7.7`, `microsandbox-linux-x86_64.tar.gz`, `sha256:b3cc4a5e3f52dfdd938a6f67ac4a9a959ddfe304bab56de4964044b8613f01bb`, `libkrunfw.so.5.6.1`). That CI helper creates `bin/`/`lib/` and symlinks for runner `$HOME/.microsandbox`, whereas `REVIEW_ADDENDUM.md` Section 5 mandates Devsy's private store bundle keeps the flat two-file archive verbatim and rejects all links. +7. **Other non-dependency commits in range** (`fa8621043b603584fcaf078c0478439cd10a1ee4` PR #1537, `901afee550d1f800382062507c424a756c988887` PR #1558, `f2ad56c8f57ebf17c7d2829ee2a848685d003d66` PR #1504, `bc4f4795e777e38ba17462bd60a060f9ee1ec127` PR #1554, `49118d4a709679557d933addb1eae4c9471e7e75` PR #1564, `6839175d95665f81d55c12e987e94e6dd650d468` PR #1563, `ac0385450ac32078abd3b42516c705f43919e954` PR #1567, `7d34768dd63ab7946416faef9e028251f88c820d` PR #1555, `587f30142b3ea6e7d5c807125b7b8667e39fa75f` PR #1560, `5cb4460600d6ceebac92d4999223840760b5bc9b` PR #1565, `00c06b940e64ccf292a69ee85f34f9dff01efa58` PR #1570, `2b30bfa6974acade7e0386a695d52d9fdfd402f6` PR #1572, `7bbd81b48f04054d8f310ffa1191a0b83f510df9` PR #1577, `7682a30c25153fccf0e98de8d6c49591fda691ae` PR #1574, `95a4699e9760b6fb8a69eec66a40bfbc19934064` PR #1579): + - Touched Apple tmpfs mount args, platform forms/parameters, OCI feature/template publishing, JetBrains IDE tests, E2E test helpers, CI disk-space/protoc bumps, and workspace docs; no provider dependency seam changed. + +--- + +## 2. Inspected Source and Test Seams Ledger (Goal 2) + +### 2.1 Status and Error Wire Envelopes +- `pkg/status/status.go`: `State` enum (`started`, `succeeded`, `failed`, `skipped` at lines 25-33), `ErrorInfo` (line 45), `Phase` (line 54), and `Event` (lines 89-100) with `OperationID` (`op-%d` from `operationSequence` at line 154 in `Run` at line 164) and `ParentOperationID`, with no `sequence` or `payload` field. +- `pkg/devcontainer/config/envelope.go`: `ResultEnvelope` (line 23), `ErrorEnvelope` (line 34), `StatusEnvelope` (lines 45-57, `SchemaVersion: 1`), `WriteCLIErrorJSON` (line 87), `ParseStatusLine` (line 109), `currentStatusFields` (lines 145-156), and `WriteStatusJSON` (line 181) enforce a closed field set (`SchemaVersion == 1`); CLI errors emit on `os.Stderr` via `cmd/root.go`. +- `desktop/src/shared/cli-error.ts`: `CliStatusEnvelope` (line 18), `isCurrentStatusEnvelope` (line 165), and `hasOnlyCurrentStatusFields` (line 202) enforce the same closed key set in TypeScript. +- Existing tests: `pkg/status/status_test.go`, `pkg/status/reporter_test.go`, `pkg/devcontainer/config/envelope_test.go`. + +### 2.2 Provider Option Precedence, `UserProvided`, and Empty Semantics +- `pkg/config/config.go`: `CurrentSchemaVersion = 1` (`pkg/config/config.go:20`), `OptionValue{Value, Password, UserProvided, Filled, Children}` (`pkg/config/config.go:103-114`). +- `cmd/provider/configure_shared.go`: `ConfigureProvider` (`configure_shared.go:49`) -> `configureProviderOptions` (line 70) runs `InheritOptionsFromEnvironment` (`DEVSY_PROVIDER__