wanderer/db/pluginsystem/manifest.go

package pluginsystem

import (
	"encoding/json"
	"errors"
	"fmt"
	"os"
	"path/filepath"
	"regexp"
	"strings"
)

const (
	DefaultPluginDir = "/data/plugins"
)

var pluginIDPattern = regexp.MustCompile(`^[a-z0-9][a-z0-9_-]*$`)

var ErrUnsupportedPluginType = errors.New("unsupported plugin type")

type LocalPlugin struct {
	Manifest Manifest `json:"manifest"`
	Dir      string   `json:"dir"`
	WASMPath string   `json:"wasmPath"`
}

// PluginDir resolves the runtime plugin directory. Production containers mount
// plugins at /data/plugins; source checkouts usually stage them at data/plugins
// and may start PocketBase either from the repo root or from db/.
func PluginDir() string {
	for _, candidate := range []string{
		DefaultPluginDir,
		"data/plugins",
		filepath.Join("..", "data", "plugins"),
	} {
		if info, err := os.Stat(candidate); err == nil && info.IsDir() {
			return candidate
		}
	}
	return DefaultPluginDir
}

// LoadLocalPlugins reads direct child directories from the plugin directory and
// returns every valid bundle. Invalid direct children are ignored by this
// compatibility helper; callers that need UI-visible errors should use
// DiscoverLocalPlugins.
func LoadLocalPlugins(dir string) ([]LocalPlugin, error) {
	plugins, _, err := DiscoverLocalPlugins(dir)
	return plugins, err
}

type LocalPluginIssue struct {
	ID    string
	Name  string
	Dir   string
	Error string
}

// DiscoverLocalPlugins reads direct child directories from the plugin directory
// and returns valid bundles plus per-directory load issues.
func DiscoverLocalPlugins(dir string) ([]LocalPlugin, []LocalPluginIssue, error) {
	if dir == "" {
		dir = PluginDir()
	}
	if _, err := os.Stat(dir); err != nil {
		if os.IsNotExist(err) {
			return []LocalPlugin{}, nil, nil
		}
		return nil, nil, err
	}

	plugins := make([]LocalPlugin, 0)
	issues := make([]LocalPluginIssue, 0)
	seen := map[string]bool{}
	entries, err := os.ReadDir(dir)
	if err != nil {
		return nil, nil, err
	}
	for _, entry := range entries {
		if !entry.IsDir() {
			continue
		}
		pluginDir := filepath.Join(dir, entry.Name())
		plugin, err := LoadLocalPlugin(pluginDir)
		if err != nil {
			if errors.Is(err, ErrUnsupportedPluginType) {
				continue
			}
			issues = append(issues, LocalPluginIssue{
				ID:    entry.Name(),
				Name:  entry.Name(),
				Dir:   pluginDir,
				Error: fmt.Sprintf("%s: %v", entry.Name(), err),
			})
			continue
		}
		if seen[plugin.Manifest.ID] {
			continue
		}
		seen[plugin.Manifest.ID] = true
		plugins = append(plugins, *plugin)
	}

	return plugins, issues, nil
}

// LoadLocalPlugin reads one plugin bundle, validates its manifest, and resolves
// the WASM entrypoint relative to the plugin directory.
func LoadLocalPlugin(dir string) (*LocalPlugin, error) {
	manifestPath := filepath.Join(dir, "plugin.json")
	data, err := os.ReadFile(manifestPath)
	if err != nil {
		return nil, err
	}

	var manifest Manifest
	if err := json.Unmarshal(data, &manifest); err != nil {
		return nil, fmt.Errorf("parse plugin.json: %w", err)
	}
	if err := ValidateManifest(manifest); err != nil {
		return nil, err
	}

	entrypoint := filepath.Clean(manifest.Runtime.Entrypoint)
	if filepath.IsAbs(entrypoint) || strings.HasPrefix(entrypoint, ".."+string(filepath.Separator)) || entrypoint == ".." {
		return nil, fmt.Errorf("runtime entrypoint must be relative to plugin directory")
	}
	wasmPath := filepath.Join(dir, entrypoint)
	if _, err := os.Stat(wasmPath); err != nil {
		return nil, fmt.Errorf("runtime entrypoint: %w", err)
	}

	return &LocalPlugin{
		Manifest: manifest,
		Dir:      dir,
		WASMPath: wasmPath,
	}, nil
}

// ValidateManifest checks the static contract that is trusted by install,
// runtime policy enforcement, auth handling, and the UI.
func ValidateManifest(manifest Manifest) error {
	if manifest.ManifestVersion == "" {
		return fmt.Errorf("manifestVersion is required")
	}
	if majorVersion(manifest.ManifestVersion) != majorVersion(ManifestVersion) {
		return fmt.Errorf("unsupported manifestVersion %q", manifest.ManifestVersion)
	}
	if !pluginIDPattern.MatchString(manifest.ID) {
		return fmt.Errorf("id must match %s", pluginIDPattern.String())
	}
	if manifest.Type != PluginTypeTrails {
		return fmt.Errorf("%w: type must be %q", ErrUnsupportedPluginType, PluginTypeTrails)
	}
	if strings.TrimSpace(manifest.Name) == "" {
		return fmt.Errorf("name is required")
	}
	if strings.TrimSpace(manifest.Version) == "" {
		return fmt.Errorf("version is required")
	}
	if manifest.Runtime.Type != RuntimeWASM {
		return fmt.Errorf("runtime.type must be %q", RuntimeWASM)
	}
	if strings.TrimSpace(manifest.Runtime.Entrypoint) == "" {
		return fmt.Errorf("runtime.entrypoint is required")
	}
	if len(manifest.Capabilities) == 0 {
		return fmt.Errorf("at least one capability is required")
	}
	if err := validateCapabilities(manifest.Capabilities); err != nil {
		return err
	}
	if err := validateAuth(manifest.Auth); err != nil {
		return err
	}
	if err := validatePermissions(manifest.Permissions, manifest.Auth); err != nil {
		return err
	}
	return nil
}

func validateCapabilities(capabilities []CapabilityManifest) error {
	seen := map[string]bool{}
	for _, capability := range capabilities {
		if strings.TrimSpace(capability.Name) == "" {
			return fmt.Errorf("capability name is required")
		}
		if strings.TrimSpace(capability.Version) == "" {
			return fmt.Errorf("capability %s version is required", capability.Name)
		}
		if strings.TrimSpace(capability.Export) == "" {
			return fmt.Errorf("capability %s export is required", capability.Name)
		}
		key := capability.Name + "." + capability.Version
		if seen[key] {
			return fmt.Errorf("duplicate capability %s", key)
		}
		seen[key] = true
	}
	return nil
}

func validateAuth(auth AuthManifest) error {
	for name, context := range auth.Contexts {
		if strings.TrimSpace(name) == "" {
			return fmt.Errorf("auth context name is required")
		}
		if err := ValidateAuthContext(name, context); err != nil {
			return err
		}
	}
	return nil
}

func validatePermissions(permissions PermissionManifest, auth AuthManifest) error {
	authContexts := map[string]bool{}
	for name := range auth.Contexts {
		authContexts[name] = true
	}
	for _, authRef := range permissions.Auth {
		if !authContexts[authRef] {
			return fmt.Errorf("permission references unknown auth context %q", authRef)
		}
	}
	if err := validateConnectors(permissions.Network.Connectors, authContexts); err != nil {
		return err
	}
	for _, host := range permissions.Network.Redirects.Hosts {
		if err := validateHost(host); err != nil {
			return err
		}
	}
	if permissions.Network.Redirects.Mode != "" && permissions.Network.Redirects.Mode != "declared_hosts_only" {
		return fmt.Errorf("unsupported redirect mode %q", permissions.Network.Redirects.Mode)
	}
	if permissions.Downloads.MaxBytes < 0 || permissions.Uploads.MaxBytes < 0 {
		return fmt.Errorf("maxBytes must not be negative")
	}
	return nil
}

func validateConnectors(connectors []ConnectorTargetPermission, authContexts map[string]bool) error {
	seen := map[string]bool{}
	for _, connector := range connectors {
		if strings.TrimSpace(connector.Name) == "" {
			return fmt.Errorf("connector name is required")
		}
		if seen[connector.Name] {
			return fmt.Errorf("duplicate connector %q", connector.Name)
		}
		seen[connector.Name] = true
		switch connector.Type {
		case ConnectorTypePublicAPI:
			if strings.TrimSpace(connector.FixedBaseURL) == "" {
				return fmt.Errorf("public_api connector %q requires fixedBaseURL", connector.Name)
			}
			if strings.TrimSpace(connector.ConfigKey) != "" {
				return fmt.Errorf("public_api connector %q must not declare configKey", connector.Name)
			}
			if _, _, err := NormalizeConnectorBase(connector.FixedBaseURL, ""); err != nil {
				return fmt.Errorf("connector %q fixedBaseURL: %w", connector.Name, err)
			}
		case ConnectorTypeConfigured:
			if strings.TrimSpace(connector.ConfigKey) == "" {
				return fmt.Errorf("configured connector %q requires configKey", connector.Name)
			}
			if strings.TrimSpace(connector.FixedBaseURL) != "" {
				return fmt.Errorf("configured connector %q must not declare fixedBaseURL", connector.Name)
			}
		default:
			return fmt.Errorf("connector %q has unsupported type %q", connector.Name, connector.Type)
		}
		for _, authRef := range connector.Auth {
			if !authContexts[authRef] {
				return fmt.Errorf("connector %q references unknown auth context %q", connector.Name, authRef)
			}
		}
		for _, prefix := range connector.AllowedPathPrefixes {
			if _, err := CanonicalURLPath(prefix); err != nil {
				return fmt.Errorf("connector %q path prefix %q: %w", connector.Name, prefix, err)
			}
		}
	}
	return nil
}

func validateHost(host string) error {
	host = strings.TrimSpace(host)
	if host == "" {
		return fmt.Errorf("network host must not be empty")
	}
	if strings.Contains(host, "://") || strings.Contains(host, "/") {
		return fmt.Errorf("network host %q must be a hostname, not a URL", host)
	}
	return nil
}

func majorVersion(version string) string {
	for i, r := range version {
		if r == '.' {
			return version[:i]
		}
	}
	return version
}