ZDDC/zddc/internal/zddc/file.go

package zddc

import (
	"os"

	"gopkg.in/yaml.v3"
)

// ACLRules holds the access-control rules at one cascade level.
//
// Three input forms, all merged at parse time into a single map keyed
// by principal (Permissions):
//
//   - acl.permissions: { principal → verb-set } — the canonical form.
//     Principal is an email pattern (contains "@") or a role name
//     (no "@"); roles are looked up via ZddcFile.Roles in this file
//     or any ancestor. Verb-set is a string drawn from {r,w,c,d,a};
//     empty string is an explicit deny.
//
//   - acl.allow: [pattern, ...] — legacy. Each pattern becomes
//     Permissions[pattern] = "rwcd" at parse time.
//
//   - acl.deny:  [pattern, ...] — legacy. Each pattern becomes
//     Permissions[pattern] = "" at parse time (explicit deny).
//
// Allow and Deny are retained on the struct for round-trip fidelity
// (and so existing operator-authored .zddc files render unchanged in
// the admin UI); the cascade evaluator reads only Permissions.
//
// JSON tags are present so this type round-trips cleanly when included
// in the external-OPA input body (see internal/policy). The canonical
// in-repo serialization is YAML; JSON is only used for OPA queries.
type ACLRules struct {
	Allow       []string          `yaml:"allow,omitempty" json:"allow,omitempty"`
	Deny        []string          `yaml:"deny,omitempty" json:"deny,omitempty"`
	Permissions map[string]string `yaml:"permissions,omitempty" json:"permissions,omitempty"`
}

// Role is the named principal-grouping primitive. Members are email
// patterns (same syntax as the legacy allow/deny entries — see
// MatchesPattern). A role defined at level L is in scope at L and all
// descendants; a level closer to the leaf may shadow an ancestor's
// role definition by redefining the same name.
type Role struct {
	Members []string `yaml:"members,omitempty" json:"members,omitempty"`
}

// ZddcFile represents the parsed contents of a .zddc configuration file.
//
// Admins is honored only in the root .zddc file (<ZDDC_ROOT>/.zddc); subdir
// .zddc files have their Admins entry ignored by IsAdmin so that someone who
// can write into a subtree cannot grant themselves admin access. ACL on the
// other hand cascades — see EffectivePolicy / AllowedWithChain.
//
// Title is read only from per-project .zddc files (the file directly inside
// each project root) by ServeProjectList; it surfaces a human-readable name
// for the project on the landing-page picker. Optional — projects without a
// title fall back to displaying the directory name.
//
// Apps is a per-directory cascade override mapping app name → source spec.
// The spec is one of: "stable" / "beta" / "alpha" (channel on the canonical
// upstream), "v0.0.4" / "v0.0" / "v0" (version pin on the canonical
// upstream), an absolute "https://..." URL (custom mirror), or a relative
// or absolute filesystem path (./local.html, /opt/zddc/foo.html).
//
// On a request for a tool HTML, zddc-server walks .zddc files leaf→root
// looking for an Apps entry; first match wins. With no entry anywhere, the
// server serves the version baked into the binary at compile time (//go:embed).
// Fetched URL sources are cached in <ZDDC_ROOT>/_app/; the cache is fetch-once
// and never re-validates — operators delete the file to force a refetch.
//
// AppsPubKey is the inline PEM of the Ed25519 public key used to verify
// signatures on URL-fetched apps artifacts. Honored only at the root
// .zddc file (same root-only treatment as Admins, for the same reason:
// it's a trust anchor; subtree write authority must not be able to
// re-anchor it). Lower priority than --apps-pubkey / ZDDC_APPS_PUBKEY:
// when both are set, the env/flag (file path) wins. Empty in either
// place = URL-fetched apps refused (only embedded + local-path apps
// work). See zddc-server's setupApps.
type ZddcFile struct {
	ACL        ACLRules          `yaml:"acl" json:"acl"`
	Admins     []string          `yaml:"admins" json:"admins,omitempty"`
	Title      string            `yaml:"title" json:"title,omitempty"`
	Apps       map[string]string `yaml:"apps,omitempty" json:"apps,omitempty"`
	AppsPubKey string            `yaml:"apps_pubkey,omitempty" json:"apps_pubkey,omitempty"`

	// Roles are named principal groups available at this level and below.
	// See Role for member syntax.
	Roles map[string]Role `yaml:"roles,omitempty" json:"roles,omitempty"`

	// CreatedBy records the email of the user who triggered the .zddc's
	// creation via the file API's mkdir post-hook (Incoming/Working/Staging
	// only). It is an audit field; the cascade evaluator does not consult
	// it. The auto-generated .zddc grants the creator's email directly via
	// ACL.Permissions, the same way operators grant access to anyone else.
	CreatedBy string `yaml:"created_by,omitempty" json:"created_by,omitempty"`
}

// ParseFile reads and parses a .zddc YAML file.
// Returns an empty ZddcFile (no rules) if the file does not exist.
func ParseFile(path string) (ZddcFile, error) {
	data, err := os.ReadFile(path)
	if os.IsNotExist(err) {
		return ZddcFile{}, nil
	}
	if err != nil {
		return ZddcFile{}, err
	}

	var zf ZddcFile
	if err := yaml.Unmarshal(data, &zf); err != nil {
		return ZddcFile{}, err
	}
	mergeLegacyACL(&zf.ACL)
	return zf, nil
}

// mergeLegacyACL folds legacy acl.allow / acl.deny lists into the
// canonical ACL.Permissions map so cascade evaluators only need to
// consult one place. Existing entries in Permissions take precedence
// (operators who specified both forms get the new form's value);
// allow entries become "rwcd" grants, deny entries become "" denies.
func mergeLegacyACL(rules *ACLRules) {
	if len(rules.Allow) == 0 && len(rules.Deny) == 0 {
		return
	}
	if rules.Permissions == nil {
		rules.Permissions = make(map[string]string, len(rules.Allow)+len(rules.Deny))
	}
	for _, pat := range rules.Allow {
		if _, present := rules.Permissions[pat]; !present {
			rules.Permissions[pat] = "rwcd"
		}
	}
	for _, pat := range rules.Deny {
		if _, present := rules.Permissions[pat]; !present {
			rules.Permissions[pat] = ""
		}
	}
}