@synopackageland/cli 0.4.0 → 0.5.0

package/templates/native-go/backend/internal/helper/jobcontract/validate.go

@@ -0,0 +1,462 @@
+package jobcontract
+
+import (
+	"io"
+	"reflect"
+	"regexp"
+	"slices"
+	"strings"
+	"unicode/utf8"
+)
+
+var (
+	packagePattern   = regexp.MustCompile(`^[A-Za-z][A-Za-z0-9]{1,63}$`)
+	versionPattern   = regexp.MustCompile(`^\d+(\.\d+){0,3}-\d{4}$`)
+	digestPattern    = regexp.MustCompile(`^[a-f0-9]{64}$`)
+	referencePattern = regexp.MustCompile(`^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$`)
+)
+
+func (r SafeReason) Error() string { return string(r) }
+func (r SafeReason) Valid() bool {
+	switch r {
+	case Invalid, Incompatible, Unsupported, Replay, Stale, Expired, Denied, Unavailable,
+		Suspended, Revoked, Fenced, Busy, LimitExceeded, ReasonCanceled, Timeout, Partial,
+		CommitUncertain, ReasonCleanupRequired, Internal:
+		return true
+	}
+	return false
+}
+func optionalReason(r SafeReason) bool { return r == "" || r.Valid() }
+func validRef(r RevisionRef) bool      { return digestPattern.MatchString(r.ID) && positive(r.Revision) }
+func validWorkerRef(r RevisionRef) bool {
+	return referencePattern.MatchString(r.ID) && positive(r.Revision)
+}
+func positive(n uint64) bool    { return n > 0 && n <= MaxSafeInteger }
+func validMode(m Mode) bool     { return m == Interactive || m == Background }
+func validAction(a Action) bool { return a == List || a == Stat || a == Read || a == ReadStream }
+
+// Values pin §5.4; manifests may only lower them. Budgets apply to the entire job.
+func HardLimits() Limits {
+	return Limits{InputBytes: MaxInputBytes, Steps: MaxSteps, TotalMS: 120000,
+		IdleMS: 10000, MetadataMS: 5000, BoundedMS: 10000, BoundedBytes: 1 << 20,
+		StreamBytes: 64 << 20, ChunkBytes: 64 << 10, OutstandingLeases: 1}
+}
+
+func ValidateLimits(l Limits) SafeReason {
+	values, ceilings := reflect.ValueOf(l), reflect.ValueOf(HardLimits())
+	for i := 0; i < values.NumField(); i++ {
+		n := values.Field(i).Uint()
+		if !positive(n) {
+			return Invalid
+		}
+		if n > ceilings.Field(i).Uint() {
+			return LimitExceeded
+		}
+	}
+	if l.IdleMS > l.TotalMS || l.MetadataMS > l.TotalMS || l.BoundedMS > l.TotalMS || l.ChunkBytes > l.StreamBytes {
+		return Invalid
+	}
+	return ""
+}
+
+func ValidateWorker(w Worker) SafeReason {
+	if w.RegistrySchema != RegistrySchema {
+		return Incompatible
+	}
+	if w.Kind != "sdk-read-plan" {
+		return Unsupported
+	}
+	if !referencePattern.MatchString(w.ID) || !positive(w.Revision) ||
+		!digestPattern.MatchString(w.HandlerBinding) || !digestPattern.MatchString(w.InputSchemaDigest) || !digestPattern.MatchString(w.OutputSchemaDigest) {
+		return Invalid
+	}
+	if len(w.Actions) == 0 || len(w.Actions) > 4 || len(w.Modes) == 0 || len(w.Modes) > 2 || len(w.Checkpoints) != 3 {
+		return Invalid
+	}
+	actions, modes, checkpoints := map[Action]bool{}, map[Mode]bool{}, map[string]bool{}
+	for _, a := range w.Actions {
+		if !validAction(a) || actions[a] {
+			return Unsupported
+		}
+		actions[a] = true
+	}
+	for _, m := range w.Modes {
+		if !validMode(m) || modes[m] {
+			return Invalid
+		}
+		modes[m] = true
+	}
+	for _, p := range w.Checkpoints {
+		if !slices.Contains([]string{"before-step", "before-chunk", "before-result"}, p) || checkpoints[p] {
+			return Invalid
+		}
+		checkpoints[p] = true
+	}
+	return ValidateLimits(w.Limits)
+}
+
+func validateSegments(ss []string, root bool) SafeReason {
+	if ss == nil || (!root && len(ss) == 0) {
+		return Invalid
+	}
+	if len(ss) > 32 {
+		return LimitExceeded
+	}
+	n := 0
+	for i, s := range ss {
+		if len(s) > 255 {
+			return LimitExceeded
+		}
+		if s == "" || s == "." || s == ".." || !utf8.ValidString(s) || strings.ContainsAny(s, "/\\\x00") {
+			return Invalid
+		}
+		n += len(s)
+		if i > 0 {
+			n++
+		}
+		if n > 4096 {
+			return LimitExceeded
+		}
+	}
+	return ""
+}
+
+func ValidateInput(in Input) SafeReason {
+	if len(in.Steps) == 0 {
+		return Invalid
+	}
+	if len(in.Steps) > MaxSteps {
+		return LimitExceeded
+	}
+	var bounded, total uint64
+	for _, s := range in.Steps {
+		if !validAction(s.Action) {
+			return Unsupported
+		}
+		if c := validateSegments(s.Segments, s.Action == List || s.Action == Stat); c != "" {
+			return c
+		}
+		switch s.Action {
+		case List:
+			if s.Limit == nil || !positive(*s.Limit) || s.MaxBytes != nil {
+				return Invalid
+			}
+			if *s.Limit > 200 {
+				return LimitExceeded
+			}
+		case Stat:
+			if s.Limit != nil || s.MaxBytes != nil {
+				return Invalid
+			}
+		case Read, ReadStream:
+			if s.MaxBytes == nil || !positive(*s.MaxBytes) || s.Limit != nil {
+				return Invalid
+			}
+			ceiling := uint64(64 << 20)
+			if s.Action == Read {
+				ceiling = 1 << 20
+			}
+			if *s.MaxBytes > ceiling {
+				return LimitExceeded
+			}
+			// Check each term before adding; no integer wrap or per-step reset.
+			total += *s.MaxBytes
+			if s.Action == Read {
+				bounded += *s.MaxBytes
+			}
+			if total > 64<<20 || bounded > 1<<20 {
+				return LimitExceeded
+			}
+		}
+	}
+	if len(encodeInput(in, "")) > MaxInputBytes {
+		return LimitExceeded
+	}
+	return ""
+}
+
+// ValidatePlan narrows a fixed input against one descriptor, never a grant/ACL.
+func ValidatePlan(w Worker, in Input, mode Mode) SafeReason {
+	if c := ValidateWorker(w); c != "" {
+		return c
+	}
+	if c := ValidateInput(in); c != "" {
+		return c
+	}
+	if !slices.Contains(w.Modes, mode) {
+		return Unsupported
+	}
+	if uint64(len(in.Steps)) > w.Limits.Steps || uint64(len(encodeInput(in, ""))) > w.Limits.InputBytes {
+		return LimitExceeded
+	}
+	var bounded, total uint64
+	for _, s := range in.Steps {
+		if !slices.Contains(w.Actions, s.Action) {
+			return Unsupported
+		}
+		if s.MaxBytes != nil {
+			total += *s.MaxBytes
+			if s.Action == Read {
+				bounded += *s.MaxBytes
+			}
+		}
+	}
+	if bounded > w.Limits.BoundedBytes || total > w.Limits.StreamBytes {
+		return LimitExceeded
+	}
+	return ""
+}
+
+func ValidateBinding(b Binding) SafeReason {
+	i := b.Inventory
+	if i.Protocol != DataProtocol || b.JobSchema != JobSchema || i.DataAccess != "relaxed" {
+		return Incompatible
+	}
+	if !packagePattern.MatchString(i.Package) || !versionPattern.MatchString(i.Version) ||
+		!digestPattern.MatchString(i.PayloadDigest) || !digestPattern.MatchString(i.RegistryDigest) {
+		return Invalid
+	}
+	if !digestPattern.MatchString(b.Epoch) || !validRef(b.Job) || !validWorkerRef(b.Worker) || !validRef(b.ParentGrant) {
+		return Invalid
+	}
+	for _, d := range []string{b.ApprovalBinding, b.CapabilityDigest, b.InputSchemaDigest, b.InputDigest} {
+		if !digestPattern.MatchString(d) {
+			return Invalid
+		}
+	}
+	if !validMode(b.Mode) {
+		return Incompatible
+	}
+	if b.Mode == Interactive && b.Delegation != nil || b.Mode == Background && (b.Delegation == nil || !validRef(*b.Delegation)) {
+		return Invalid
+	}
+	return ""
+}
+
+// CompareBinding checks every field. It cannot validate a ticket or authorize I/O.
+func CompareBinding(got, expected Binding) SafeReason {
+	if c := ValidateBinding(got); c != "" {
+		return c
+	}
+	if c := ValidateBinding(expected); c != "" {
+		return c
+	}
+	if !reflect.DeepEqual(got, expected) {
+		return Incompatible
+	}
+	return ""
+}
+
+func ValidateControl(r Control) SafeReason {
+	if c := ValidateBinding(r.Binding); c != "" {
+		return c
+	}
+	if !validRef(r.Intent) || !digestPattern.MatchString(r.Nonce) || !digestPattern.MatchString(r.Ticket) {
+		return Invalid
+	}
+	switch r.Op {
+	case "jobs.submit", "jobs.cancel":
+	case "background.revoke":
+		if r.Binding.Mode != Background {
+			return Incompatible
+		}
+	default:
+		return Unsupported
+	}
+	return ""
+}
+
+func validPrincipal(p Principal) bool {
+	return p.IdentityBasis == "uid-username" && p.UID != 0 && p.UID != ^uint32(0) &&
+		p.Username != "" && len(p.Username) <= 255 && utf8.ValidString(p.Username) && !strings.ContainsAny(p.Username, "\x00/\\\r\n")
+}
+func validatePrivate(b PrivateBinding) SafeReason {
+	if c := ValidateBinding(b.Binding); c != "" {
+		return c
+	}
+	if !validPrincipal(b.Actor) {
+		return Invalid
+	}
+	if b.Binding.Mode == Interactive && !digestPattern.MatchString(b.SessionRef) || b.Binding.Mode == Background && b.SessionRef != "" {
+		return Invalid
+	}
+	return ""
+}
+
+func ValidateIntent(i Intent) SafeReason {
+	if i.JobSchema != JobSchema {
+		return Incompatible
+	}
+	if c := validatePrivate(i.Binding); c != "" {
+		return c
+	}
+	if !digestPattern.MatchString(i.ID) || !positive(i.Revision) || !digestPattern.MatchString(i.SummaryDigest) ||
+		!positive(i.CreatedAt) || !positive(i.ExpiresAt) || i.ExpiresAt <= i.CreatedAt || i.ExpiresAt-i.CreatedAt > IntentTTLMS {
+		return Invalid
+	}
+	d, c := InputDigest(i.Input, i.Binding.Binding.InputSchemaDigest)
+	if c != "" {
+		return c
+	}
+	if d != i.Binding.Binding.InputDigest {
+		return Invalid
+	}
+	return ""
+}
+
+func ValidateBackground(r BackgroundRecord) SafeReason {
+	if r.BackgroundSchema != BackgroundSchema {
+		return Incompatible
+	}
+	if c := validatePrivate(r.Binding); c != "" {
+		return c
+	}
+	if r.Binding.Binding.Mode != Background || r.Issuer != r.Binding.Actor || !validPrincipal(r.Issuer) {
+		return Invalid
+	}
+	if !positive(r.CreatedAt) || !positive(r.ExpiresAt) || !positive(r.NotBefore) || r.ExpiresAt <= r.CreatedAt ||
+		r.ExpiresAt-r.CreatedAt > MaxBackgroundTTLMS || r.NotBefore < r.CreatedAt || r.NotBefore >= r.ExpiresAt || !optionalReason(r.Reason) {
+		return Invalid
+	}
+	if r.ExecutionKey != "" && !digestPattern.MatchString(r.ExecutionKey) {
+		return Invalid
+	}
+	switch r.State {
+	case "active":
+		if r.ExecutionKey != "" || r.Reason != "" {
+			return Invalid
+		}
+	case "consumed":
+		if r.ExecutionKey == "" || r.Reason != "" {
+			return Invalid
+		}
+	case "expired", "revoked", "suspended":
+		if r.Reason == "" {
+			return Invalid
+		} // retain burned key
+	default:
+		return Invalid
+	}
+	return ""
+}
+
+func ValidateProgress(p Progress, previous *Progress) SafeReason {
+	if p.Sequence > MaxSafeInteger || p.CompletedUnits > MaxSafeInteger || p.BytesRead > 64<<20 || p.BytesWritten != 0 {
+		return Invalid
+	}
+	if !slices.Contains([]string{"starting", "metadata", "reading", "finishing"}, p.Phase) {
+		return Invalid
+	}
+	if p.TotalUnits != nil && (*p.TotalUnits > MaxSafeInteger || p.CompletedUnits > *p.TotalUnits) {
+		return Invalid
+	}
+	if previous != nil && (p.Sequence <= previous.Sequence || p.CompletedUnits < previous.CompletedUnits || p.BytesRead < previous.BytesRead ||
+		(previous.TotalUnits != nil && (p.TotalUnits == nil || *p.TotalUnits != *previous.TotalUnits))) {
+		return Invalid
+	}
+	return ""
+}
+
+func terminal(s State) bool {
+	return s == Succeeded || s == Failed || s == Canceled || s == Interrupted
+}
+
+// Allowed edges are shape constraints only, never durability/credential/Q proof.
+func TransitionAllowed(from, to State) bool {
+	switch from {
+	case Pending:
+		return to == Running || to == CancelRequested || to == Failed || to == Interrupted || to == CleanupRequired
+	case Running:
+		return to == Succeeded || to == Failed || to == CancelRequested || to == Interrupted || to == CleanupRequired
+	case CancelRequested:
+		return to == Draining || to == Canceled || to == Failed || to == Interrupted || to == CleanupRequired
+	case Draining, CleanupRequired:
+		return to == Canceled || to == Failed || to == Interrupted || (from == Draining && to == CleanupRequired)
+	}
+	return false
+}
+
+func ValidateJob(j Job) SafeReason {
+	if c := ValidateBinding(j.Binding); c != "" {
+		return c
+	}
+	if !optionalReason(j.Reason) || !positive(j.AcceptedAt) {
+		return Invalid
+	}
+	if c := ValidateProgress(j.Progress, nil); c != "" {
+		return c
+	}
+	if j.StartedAt != nil && (!positive(*j.StartedAt) || *j.StartedAt < j.AcceptedAt) {
+		return Invalid
+	}
+	if j.FinishedAt != nil && (!positive(*j.FinishedAt) || *j.FinishedAt < j.AcceptedAt || j.StartedAt != nil && *j.FinishedAt < *j.StartedAt) {
+		return Invalid
+	}
+	if terminal(j.State) {
+		if j.FinishedAt == nil {
+			return Invalid
+		}
+	} else if j.FinishedAt != nil || j.Drained {
+		return Invalid
+	}
+	switch j.State {
+	case Pending:
+		if j.StartedAt != nil || j.CancelRequested {
+			return Invalid
+		}
+	case Running:
+		if j.StartedAt == nil || j.CancelRequested {
+			return Invalid
+		}
+	case CancelRequested, Draining:
+		if !j.CancelRequested {
+			return Invalid
+		}
+	case CleanupRequired:
+		if j.Reason != ReasonCleanupRequired {
+			return Invalid
+		}
+	case Succeeded:
+		if j.StartedAt == nil || !j.Drained || j.EffectsUnknown || j.Reason != "" {
+			return Invalid
+		}
+	case Failed, Interrupted:
+		if j.Reason == "" {
+			return Invalid
+		}
+	case Canceled:
+		if !j.CancelRequested || j.Reason == "" {
+			return Invalid
+		}
+	default:
+		return Invalid
+	}
+	return ""
+}
+
+func decodeValidated[T any](r io.Reader, limit int, validate func(T) SafeReason) (T, SafeReason) {
+	var v T
+	if c := decodeObject(r, &v, limit); c != "" {
+		return *new(T), c
+	}
+	if c := validate(v); c != "" {
+		return *new(T), c
+	}
+	return v, ""
+}
+func DecodeInput(r io.Reader) (Input, SafeReason) {
+	return decodeValidated(r, MaxInputBytes, ValidateInput)
+}
+func DecodeWorker(r io.Reader) (Worker, SafeReason) {
+	return decodeValidated(r, MaxControlBytes, ValidateWorker)
+}
+func DecodeControl(r io.Reader) (Control, SafeReason) {
+	return decodeValidated(r, MaxControlBytes, ValidateControl)
+}
+func DecodeIntent(r io.Reader) (Intent, SafeReason) {
+	return decodeValidated(r, MaxArtifactBytes, ValidateIntent)
+}
+func DecodeBackground(r io.Reader) (BackgroundRecord, SafeReason) {
+	return decodeValidated(r, MaxArtifactBytes, ValidateBackground)
+}
+func DecodeJob(r io.Reader) (Job, SafeReason) { return decodeValidated(r, MaxStatusBytes, ValidateJob) }

package/templates/native-go/backend/internal/helper/lease.go

@@ -0,0 +1,112 @@
+package helper
+
+import (
+	"errors"
+	"io"
+	"os"
+	"path/filepath"
+	"syscall"
+)
+
+// Lease binds the unreplaceable lifetime witness to an approved epoch. Both
+// supervisor and child retain the same flock description until kernel exit.
+type Lease struct {
+	Device uint64 `json:"device"`
+	Inode  uint64 `json:"inode"`
+}
+
+func leasePath(c Client, l *Lifecycle) string {
+	return filepath.Join(c.StateDir, "lifetime-"+l.Epoch+".lock")
+}
+
+func createLifetime(c Client, l *Lifecycle) error {
+	if l == nil || !l.valid() || l.Lease != nil {
+		return errTrust
+	}
+	f, err := os.OpenFile(leasePath(c, l), os.O_CREATE|os.O_EXCL|os.O_RDWR|syscall.O_NOFOLLOW, 0600)
+	if err != nil {
+		return err
+	}
+	defer f.Close()
+	if _, err = f.WriteString(l.Epoch); err != nil {
+		return err
+	}
+	if err = f.Sync(); err != nil {
+		return err
+	}
+	st, err := f.Stat()
+	if err != nil {
+		return err
+	}
+	stat, ok := st.Sys().(*syscall.Stat_t)
+	if !ok {
+		return errTrust
+	}
+	l.Lease = &Lease{Device: uint64(stat.Dev), Inode: stat.Ino}
+	if err = validateLifetime(c, l, f); err != nil {
+		return err
+	}
+	return syncDirectory(c.StateDir)
+}
+
+func syncDirectory(path string) error {
+	d, err := os.Open(path)
+	if err != nil {
+		return err
+	}
+	defer d.Close()
+	return d.Sync()
+}
+
+func validateLifetime(c Client, l *Lifecycle, f *os.File) error {
+	if l == nil || !l.valid() || l.Lease == nil || l.Lease.Inode == 0 {
+		return errTrust
+	}
+	if err := protected(c.StateDir, c.Owner, true); err != nil {
+		return err
+	}
+	st, err := f.Stat()
+	if err != nil {
+		return err
+	}
+	stat, ok := st.Sys().(*syscall.Stat_t)
+	if !ok || !st.Mode().IsRegular() || st.Mode().Perm() != 0600 || stat.Uid != c.Owner || stat.Nlink != 1 || st.Size() != 64 || uint64(stat.Dev) != l.Lease.Device || stat.Ino != l.Lease.Inode {
+		return errTrust
+	}
+	path, err := os.Lstat(leasePath(c, l))
+	if err != nil {
+		return err
+	}
+	if !path.Mode().IsRegular() || !os.SameFile(st, path) {
+		return errTrust
+	}
+	var b [64]byte
+	n, err := f.ReadAt(b[:], 0)
+	if (err != nil && !errors.Is(err, io.EOF)) || n != 64 || string(b[:]) != l.Epoch {
+		return errTrust
+	}
+	return lifetimeFilesystem(f)
+}
+
+func acquireLifetime(c Client, l *Lifecycle) (*os.File, error) {
+	if l == nil || !l.valid() || l.Lease == nil {
+		return nil, errTrust
+	}
+	// Never create on open: a missing historical witness cannot be repaired.
+	f, err := os.OpenFile(leasePath(c, l), os.O_RDWR|syscall.O_NOFOLLOW, 0)
+	if err != nil {
+		return nil, err
+	}
+	if err = validateLifetime(c, l, f); err == nil {
+		err = syscall.Flock(int(f.Fd()), syscall.LOCK_EX|syscall.LOCK_NB)
+	}
+	if err == nil {
+		err = validateLifetime(c, l, f)
+	}
+	if err != nil {
+		f.Close()
+		return nil, err
+	}
+	// Closing our independently opened description releases only our lock.
+	return f, nil
+}

package/templates/native-go/backend/internal/helper/lease_linux.go

@@ -0,0 +1,44 @@
+package helper
+
+import (
+	"os"
+	"syscall"
+)
+
+// Network filesystems have different flock semantics and are not supported.
+func lifetimeFilesystem(f *os.File) error {
+	var s syscall.Statfs_t
+	if err := syscall.Fstatfs(int(f.Fd()), &s); err != nil {
+		return err
+	}
+	switch uint64(s.Type) {
+	case 0xef53, 0x9123683e, 0x58465342, 0x01021994, 0x858458f6, 0x794c7630: // ext, btrfs, xfs, tmpfs, ramfs, overlayfs
+		return nil
+	}
+	return errTrust
+}
+
+// These descriptors deliberately have process lifetime. No defer Close or
+// LOCK_UN: release before child kernel exit would create a false death proof.
+var processLifetime *os.File
+
+func inheritLifetime(c Client) error {
+	r, err := readRecord(c.StateDir, 0)
+	if err != nil || r.Inventory != c.Expected || !r.Enabled || r.Lifecycle == nil || r.Lifecycle.Phase != "running" {
+		return errTrust
+	}
+	f := os.NewFile(3, "inherited-lifetime")
+	if f == nil {
+		return errTrust
+	}
+	if err = validateLifetime(c, r.Lifecycle, f); err == nil {
+		err = syscall.Flock(3, syscall.LOCK_EX|syscall.LOCK_NB)
+	}
+	if err != nil {
+		f.Close()
+		return err
+	}
+	syscall.CloseOnExec(3)
+	processLifetime = f
+	return nil
+}

package/templates/native-go/backend/internal/helper/lease_other.go

@@ -0,0 +1,8 @@
+//go:build !linux
+
+package helper
+
+import "os"
+
+// Non-Linux hosts run fixture tests only; RunLinux refuses production control.
+func lifetimeFilesystem(*os.File) error { return nil }

package/templates/native-go/backend/internal/helper/legacy_authority_schema_linux_test.go

@@ -0,0 +1,34 @@
+//go:build linux && !synopkgland_sdk_workers
+
+package helper
+
+import (
+	"bytes"
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestLegacyAuthorityUnknownSchemaDoesNotOverwrite(t *testing.T) {
+	for _, raw := range []string{`{"grantSchema":2,"storeRevision":7,"grants":[]}`, `{"grantSchema":99,"storeRevision":7,"grants":[]}`, `{"grantSchema":1,"storeRevision":7,"grants":[],"background":[]}`} {
+		dir, inventory, _ := rootGrantFixture(t)
+		path := filepath.Join(dir, "grants.json")
+		if err := os.WriteFile(path, []byte(raw), 0600); err != nil {
+			t.Fatal(err)
+		}
+		repo := openRootGrantRepository(t, dir, inventory)
+		if _, code := NewGrantAuthority(repo, nil, nil, nil); code == "" {
+			t.Fatal("legacy read new schema")
+		}
+		if code := repo.Transact(func(_ GrantPolicy, s *GrantStore) (bool, Code) {
+			*s = GrantStore{Schema: 1, Revision: 1, Grants: []Grant{}}
+			return true, ""
+		}); code != ErrFenced {
+			t.Fatal("legacy overwrote unsupported store", code)
+		}
+		after, err := os.ReadFile(path)
+		if err != nil || !bytes.Equal([]byte(raw), after) {
+			t.Fatal("unknown bytes changed", err)
+		}
+	}
+}

package/templates/native-go/backend/internal/helper/legacy_authority_schema_test.go

@@ -0,0 +1,6 @@
+//go:build !synopkgland_sdk_workers
+
+package helper
+
+// Ordinary behavioral fixtures start with a current envelope; migration has separate tests.
+const testAuthoritySchema = 1