diff --git a/internal/domain/storepkg/descriptor.go b/internal/domain/storepkg/descriptor.go new file mode 100644 index 000000000..124621c85 --- /dev/null +++ b/internal/domain/storepkg/descriptor.go @@ -0,0 +1,163 @@ +// Package storepkg defines and validates declarative Archie store packages. +package storepkg + +import ( + "bytes" + "errors" + "fmt" + "io" + "path" + "regexp" + "strings" + + "gopkg.in/yaml.v3" +) + +const APIVersion = "dev.archie.package.v1" + +var digestPattern = regexp.MustCompile(`^sha256:[a-f0-9]{64}$`) + +// Descriptor is the dev.archie.package.v1 manifest annotation payload. +type Descriptor struct { + APIVersion string `yaml:"apiVersion"` + DisplayName string `yaml:"displayName"` + Description string `yaml:"description"` + Version string `yaml:"version"` + Contributes Contributions `yaml:"contributes"` + Requires []PackageRef `yaml:"requires"` + Authority Authority `yaml:"authority"` + Files []File `yaml:"files"` +} + +// Contributions names the declarative families supplied by a package. +type Contributions struct { + Workflows []string `yaml:"workflows"` + Prompts []string `yaml:"prompts"` + Skills []string `yaml:"skills"` + MCPServers []string `yaml:"mcpServers"` + Defaults []string `yaml:"defaults"` +} + +// PackageRef identifies a required package or Kit. References are pinned to +// immutable content digests so dependency resolution cannot drift by tag. +type PackageRef struct { + Name string `yaml:"name"` + Digest string `yaml:"digest"` +} + +// Authority lists the grants the package needs to operate. +type Authority struct { + CredentialServices []string `yaml:"credentialServices"` + EgressHosts []string `yaml:"egressHosts"` + ForgePermissions []string `yaml:"forgePermissions"` + Triggers []string `yaml:"triggers"` + Tools []string `yaml:"tools"` +} + +// File describes one path carried in the package layer and its Unix mode. +type File struct { + Path string `yaml:"path"` + Mode uint32 `yaml:"mode"` +} + +// Decode strictly decodes one YAML document and validates the descriptor. +// Unknown fields and additional YAML documents are errors. +func Decode(r io.Reader) (Descriptor, error) { + data, err := io.ReadAll(r) + if err != nil { + return Descriptor{}, fmt.Errorf("read package descriptor: %w", err) + } + decoder := yaml.NewDecoder(bytes.NewReader(data)) + decoder.KnownFields(true) + var descriptor Descriptor + if err := decoder.Decode(&descriptor); err != nil { + return Descriptor{}, fmt.Errorf("decode package descriptor: %w", err) + } + var extra yaml.Node + if err := decoder.Decode(&extra); !errors.Is(err, io.EOF) { + if err != nil { + return Descriptor{}, fmt.Errorf("decode trailing package descriptor: %w", err) + } + return Descriptor{}, fmt.Errorf("decode package descriptor: multiple YAML documents are not allowed") + } + if err := descriptor.Validate(); err != nil { + return Descriptor{}, err + } + return descriptor, nil +} + +// Validate checks descriptor identity, references, authority values, and +// that every listed package file remains declarative and non-executable. +func (d Descriptor) Validate() error { + if d.APIVersion != APIVersion { + return fmt.Errorf("apiVersion must be %q", APIVersion) + } + if strings.TrimSpace(d.DisplayName) == "" { + return fmt.Errorf("display name is required") + } + if strings.TrimSpace(d.Version) == "" { + return fmt.Errorf("version is required") + } + if !d.hasContribution() { + return fmt.Errorf("at least one package contribution is required") + } + for i, ref := range d.Requires { + if strings.TrimSpace(ref.Name) == "" { + return fmt.Errorf("required package %d: name is required", i) + } + if !digestPattern.MatchString(ref.Digest) { + return fmt.Errorf("required package %q digest must be a sha256 digest", ref.Name) + } + } + for _, permission := range d.Authority.ForgePermissions { + if !validForgePermission(permission) { + return fmt.Errorf("invalid forge permission %q", permission) + } + } + for i, file := range d.Files { + if err := validateFile(file); err != nil { + return fmt.Errorf("package file %d: %w", i, err) + } + } + return nil +} + +func (d Descriptor) hasContribution() bool { + return len(d.Contributes.Workflows)+len(d.Contributes.Prompts)+len(d.Contributes.Skills)+ + len(d.Contributes.MCPServers)+len(d.Contributes.Defaults) > 0 +} + +func validForgePermission(permission string) bool { + switch permission { + case "read", "comment", "review", "push", "open_pr": + return true + default: + return false + } +} + +func validateFile(file File) error { + clean := path.Clean(file.Path) + if file.Path == "" || clean == "." || clean == ".." || strings.HasPrefix(clean, "../") || path.IsAbs(file.Path) { + return fmt.Errorf("path must be a relative package path") + } + if file.Mode&0o111 != 0 { + return fmt.Errorf("executable file modes are not allowed") + } + if isHostCodePath(clean) { + return fmt.Errorf("host code is not declarative package content") + } + return nil +} + +func isHostCodePath(file string) bool { + ext := strings.ToLower(path.Ext(file)) + switch ext { + case ".go", ".yaegi", ".sh", ".bash", ".zsh", ".fish", ".ksh", ".csh", + ".py", ".pyw", ".rb", ".pl", ".pm", ".php", ".lua", ".tcl", ".r", + ".js", ".mjs", ".cjs", ".ts", ".bat", ".cmd", ".ps1": + return true + default: + return false + } +} diff --git a/internal/domain/storepkg/descriptor_test.go b/internal/domain/storepkg/descriptor_test.go new file mode 100644 index 000000000..5ceca3639 --- /dev/null +++ b/internal/domain/storepkg/descriptor_test.go @@ -0,0 +1,121 @@ +package storepkg + +import ( + "strings" + "testing" +) + +const validDescriptor = `apiVersion: dev.archie.package.v1 +displayName: Review workflow +description: Reviews pull requests +version: 1.2.3 +contributes: + workflows: [review] + prompts: [reviewer] + skills: [review-skill] + mcpServers: [forge] + defaults: [review-profile] +requires: + - name: review-kit + digest: sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa +authority: + credentialServices: [github] + egressHosts: [api.github.com] + forgePermissions: [read, comment, review, push, open_pr] + triggers: [watched_repository_events, schedules] + tools: [archie.search] +files: + - path: workflows/review.yaml + mode: 0644 +` + +func TestDecodeDescriptor(t *testing.T) { + got, err := Decode(strings.NewReader(validDescriptor)) + if err != nil { + t.Fatal(err) + } + if got.APIVersion != "dev.archie.package.v1" || got.DisplayName != "Review workflow" || got.Version != "1.2.3" { + t.Fatalf("descriptor metadata = %#v", got) + } + if len(got.Contributes.Workflows) != 1 || len(got.Contributes.MCPServers) != 1 || len(got.Requires) != 1 { + t.Fatalf("descriptor contributions/requirements = %#v", got) + } + if len(got.Authority.ForgePermissions) != 5 || got.Files[0].Path != "workflows/review.yaml" { + t.Fatalf("descriptor authority/files = %#v", got) + } +} + +func TestDecodeDescriptorRejectsUnknownFields(t *testing.T) { + input := strings.Replace(validDescriptor, "displayName: Review workflow", "displayName: Review workflow\nunknownField: surprise", 1) + if _, err := Decode(strings.NewReader(input)); err == nil { + t.Fatal("Decode accepted unknown field") + } +} + +func TestDescriptorValidate(t *testing.T) { + cases := []struct { + name string + edit func(*Descriptor) + wantErr string + }{ + {name: "valid", edit: func(*Descriptor) {}}, + {name: "missing display name", edit: func(d *Descriptor) { d.DisplayName = "" }, wantErr: "display name"}, + {name: "unsupported api version", edit: func(d *Descriptor) { d.APIVersion = "dev.archie.package.v2" }, wantErr: "apiVersion"}, + {name: "unpinned kit", edit: func(d *Descriptor) { d.Requires = []PackageRef{{Name: "kit", Digest: ""}} }, wantErr: "digest"}, + {name: "tag kit", edit: func(d *Descriptor) { d.Requires = []PackageRef{{Name: "kit", Digest: "latest"}} }, wantErr: "digest"}, + { + name: "go source", edit: func(d *Descriptor) { + d.Files = []File{{Path: "plugin/main.go", Mode: 0o644}} + }, wantErr: "declarative", + }, + { + name: "yaegi source", edit: func(d *Descriptor) { + d.Files = []File{{Path: "plugin/main.yaegi", Mode: 0o644}} + }, wantErr: "declarative", + }, + { + name: "script", edit: func(d *Descriptor) { + d.Files = []File{{Path: "hooks/setup.sh", Mode: 0o644}} + }, wantErr: "declarative", + }, + { + name: "executable mode", edit: func(d *Descriptor) { + d.Files = []File{{Path: "workflows/review.yaml", Mode: 0o755}} + }, wantErr: "executable", + }, + { + name: "full executable mode", edit: func(d *Descriptor) { + d.Files = []File{{Path: "workflows/review.yaml", Mode: 0o100755}} + }, wantErr: "executable", + }, + {name: "invalid forge permission", edit: func(d *Descriptor) { d.Authority.ForgePermissions = []string{"admin"} }, wantErr: "forge permission"}, + } + + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + d, err := Decode(strings.NewReader(validDescriptor)) + if err != nil { + t.Fatal(err) + } + tc.edit(&d) + err = d.Validate() + if tc.wantErr == "" { + if err != nil { + t.Fatalf("Validate() error = %v", err) + } + return + } + if err == nil || !strings.Contains(strings.ToLower(err.Error()), strings.ToLower(tc.wantErr)) { + t.Fatalf("Validate() error = %v, want substring %q", err, tc.wantErr) + } + }) + } +} + +func TestDecodeRejectsMalformedAndMultipleDocuments(t *testing.T) { + for _, input := range []string{"displayName: [", validDescriptor + "---\n" + validDescriptor} { + if _, err := Decode(strings.NewReader(input)); err == nil { + t.Fatalf("Decode accepted invalid input %q", input) + } + } +}