feat(storepkg): package descriptor with strict decoding and validation
This commit is contained in:
2 files changed
+284
No files matched your search
@@ -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
|
||||
}
|
||||
}
|
||||
@@ -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)
|
||||
}
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user