feat(storepkg): package descriptor with strict decoding and validation

This commit is contained in:
sam committed 2026-09-26 09:13:39 +10:00
1 parent 0eef8ed5ba
commit bc2ce7aca5
2 files changed
+284

No files matched your search

+163
View File
@@ -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
}
}
+121
View File
@@ -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)
}
}
}