@synopackageland/cli 0.3.10 → 0.4.1

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

@@ -0,0 +1,242 @@
+package helper
+
+import "time"
+
+// These are S0 contracts only. No data operation is served by the M1 socket.
+const (
+	DataProtocol         = 2
+	GrantSchema          = 1
+	MaxHealthBytes       = 4096
+	MaxControlBytes      = 16 * 1024
+	MaxGrants            = 256 // includes revoked tombstones
+	MaxGrantStoreBytes   = 1 << 20
+	MaxPageEntries       = 200
+	MaxMetadataBytes     = 256 * 1024
+	MaxLiveIntents       = 8 // per native subject
+	MaxPathBytes         = 4096
+	MaxPathSegments      = 32
+	MaxSegmentBytes      = 255
+	MaxBoundedBytes      = 1 << 20
+	MaxTransferBytes     = 64 << 20
+	MaxChunkBytes        = 64 << 10
+	MaxOutstandingLeases = 1 // per transfer
+	MaxPackageOperations = 4
+	MaxSubjectOperations = 2
+	MaxReplayEntries     = 256 // per epoch/session window; full means busy, never eviction
+	ControlTimeout       = time.Second
+	MetadataTimeout      = 5 * time.Second
+	BoundedTimeout       = 10 * time.Second
+	CandidateTTL         = 60 * time.Second
+	IntentTTL            = 30 * time.Second
+	StreamIdleTimeout    = 10 * time.Second
+	StreamTotalTimeout   = 120 * time.Second
+	NativeProofFreshness = 2 * time.Second
+	RevokeDrainTimeout   = 2 * time.Second
+	TerminateGrace       = time.Second
+)
+
+type Action string
+
+const (
+	ActionList        Action = "nas.files.list"
+	ActionStat        Action = "nas.files.stat"
+	ActionRead        Action = "nas.files.read"
+	ActionReadStream  Action = "nas.files.read-stream"
+	ActionCreate      Action = "nas.files.create"
+	ActionWriteStream Action = "nas.files.write-stream"
+	ActionPublish     Action = "nas.files.publish"
+)
+
+func (a Action) ReadOnly() bool {
+	return a == ActionList || a == ActionStat || a == ActionRead || a == ActionReadStream
+}
+
+// Code deliberately has no underlying native error, path, credential or stderr.
+type Code string
+
+const (
+	ErrInvalid         Code = "invalid-request"
+	ErrIncompatible    Code = "incompatible"
+	ErrUnsupported     Code = "unsupported"
+	ErrReplay          Code = "replay"
+	ErrStale           Code = "stale"
+	ErrExpired         Code = "expired"
+	ErrDenied          Code = "denied"
+	ErrUnavailable     Code = "unavailable"
+	ErrSuspended       Code = "suspended"
+	ErrRevoked         Code = "revoked"
+	ErrFenced          Code = "fenced"
+	ErrBusy            Code = "busy"
+	ErrLimit           Code = "limit-exceeded"
+	ErrCanceled        Code = "canceled"
+	ErrTimeout         Code = "timeout"
+	ErrPartial         Code = "partial"
+	ErrCommitUncertain Code = "commit-uncertain"
+	ErrCleanupRequired Code = "cleanup-required"
+	ErrInternal        Code = "internal"
+)
+
+func (c Code) Error() string { return string(c) }
+func (c Code) Valid() bool {
+	switch c {
+	case ErrInvalid, ErrIncompatible, ErrUnsupported, ErrReplay, ErrStale, ErrExpired,
+		ErrDenied, ErrUnavailable, ErrSuspended, ErrRevoked, ErrFenced, ErrBusy, ErrLimit,
+		ErrCanceled, ErrTimeout, ErrPartial, ErrCommitUncertain, ErrCleanupRequired, ErrInternal:
+		return true
+	}
+	return false
+}
+
+type SafeError struct {
+	Code        Code   `json:"code"`
+	OperationID string `json:"operationId,omitempty"`
+}
+
+type ScopeKind string
+
+const (
+	ScopeShared   ScopeKind = "app-shared"
+	ScopePersonal ScopeKind = "user-personal"
+)
+
+// Principal and Scope are root-derived authority records, never caller claims.
+// Strict proof references require S1 validation; the opt-in managed pilot uses
+// a separately labeled SDK enrollment and the SAME S3 admission guard. It never
+// claims native incarnation. Name/UID/dev/inode are not continuity.
+type Principal struct {
+	Kind        string `json:"kind"` // local only
+	SubjectRef  string `json:"subjectRef"`
+	InstanceRef string `json:"instanceRef"`
+	// Explicit S1R discriminator. Omitted legacy fields remain strict/managed;
+	// no decoder may reinterpret their references as UID/username evidence.
+	IdentityBasis string `json:"identityBasis,omitempty"`
+	UID           uint32 `json:"uid,omitempty"`
+	Username      string `json:"username,omitempty"`
+}
+
+type Scope struct {
+	Kind       ScopeKind `json:"kind"`
+	TargetKind string    `json:"targetKind"` // directory only
+	AnchorRef  string    `json:"anchorRef"`  // trusted share or own-home anchor
+	Segments   []string  `json:"segments"`
+	ObjectRef  string    `json:"objectRef"`
+	MountRef   string    `json:"mountRef"` // validated local mount identity, not just st_dev
+}
+
+type ContinuityBinding struct {
+	Epoch        string `json:"epoch"`
+	SubjectProof string `json:"subjectProof"`
+	ScopeProof   string `json:"scopeProof"`
+}
+
+type GrantState string
+
+const (
+	GrantActive    GrantState = "active"
+	GrantSuspended GrantState = "suspended"
+	GrantRevoked   GrantState = "revoked"
+)
+
+type Grant struct {
+	Schema           int               `json:"grantSchema"`
+	ID               string            `json:"grantId"`
+	Revision         uint64            `json:"grantRevision"`
+	Inventory        Inventory         `json:"inventory"`
+	ApprovalBinding  string            `json:"approvalBinding"`
+	CapabilityDigest string            `json:"capabilityDigest"`
+	Owner            Principal         `json:"owner"`
+	Issuer           Principal         `json:"issuer"`
+	Scope            Scope             `json:"scope"`
+	Actions          []Action          `json:"actions"`
+	State            GrantState        `json:"state"`
+	CreatedAt        int64             `json:"createdAt"` // Unix milliseconds
+	RevokedAt        int64             `json:"revokedAt,omitempty"`
+	Reason           Code              `json:"reason,omitempty"`
+	LastValidated    ContinuityBinding `json:"lastValidatedBinding"`
+}
+
+// EffectiveState never restores a revoked or suspended grant. Restart callers
+// must pass continuous=false even if a restored epoch happens to match.
+func (g Grant) EffectiveState(current ContinuityBinding, continuous bool) GrantState {
+	if g.State == GrantRevoked {
+		return GrantRevoked
+	}
+	if g.State != GrantActive || !continuous || !validContinuity(current) || g.LastValidated != current {
+		return GrantSuspended
+	}
+	return GrantActive
+}
+
+type GrantStore struct {
+	Schema   int     `json:"grantSchema"`
+	Revision uint64  `json:"storeRevision"`
+	Grants   []Grant `json:"grants"`
+}
+
+// Intent is ephemeral and server-derived. Confirmation consumes it only after
+// fresh native identity/role/ACL and exact summary/epoch/candidate revalidation.
+type Intent struct {
+	ID            string    `json:"intentId"`
+	Inventory     Inventory `json:"inventory"`
+	Epoch         string    `json:"epoch"`
+	SubjectRef    string    `json:"subjectRef"`
+	SessionRef    string    `json:"sessionRef"`
+	CandidateID   string    `json:"candidateId"`
+	ScopeKind     ScopeKind `json:"scopeKind"`
+	Actions       []Action  `json:"actions"`
+	SummaryDigest string    `json:"summaryDigest"`
+	ExpiresAt     int64     `json:"expiresAt"` // Unix milliseconds; at most IntentTTL
+}
+
+type ListArgs struct {
+	Segments []string `json:"segments"`
+	Limit    uint32   `json:"limit"`
+	Cursor   string   `json:"cursor,omitempty"`
+}
+type StatArgs struct {
+	Segments []string `json:"segments"`
+}
+type ReadArgs struct {
+	Segments []string `json:"segments"`
+	MaxBytes uint64   `json:"maxBytes"` // no caller offsets/ranges/resume
+}
+type CreateArgs struct {
+	Segments  []string `json:"segments"`
+	Bytes     uint64   `json:"bytes"` // bulk data never carried in JSON
+	Exclusive bool     `json:"exclusive"`
+}
+type WriteStreamArgs struct {
+	Segments []string `json:"segments"`
+	MaxBytes uint64   `json:"maxBytes"`
+}
+type PublishArgs struct {
+	StageID     string `json:"stageId"`
+	NoOverwrite bool   `json:"noOverwrite"`
+}
+
+type Entry struct {
+	EntryID string `json:"entryId"`
+	Name    string `json:"name"` // visible only after actor ACL
+	Kind    string `json:"kind"` // directory or regular
+	Bytes   uint64 `json:"bytes"`
+}
+type ListResult struct {
+	Entries []Entry `json:"entries"`
+	Cursor  string  `json:"cursor,omitempty"` // opaque, bound to actor/grant/revision/epoch
+}
+type ReadResult struct {
+	Bytes uint64 `json:"bytes"`
+} // separate bounded binary relay
+type MutationReceipt struct {
+	EffectsUnknown bool   `json:"effectsUnknown,omitempty"`
+	Created        bool   `json:"created"`
+	Published      bool   `json:"published"`
+	BytesWritten   uint64 `json:"bytesWritten"`
+	Committed      bool   `json:"committed"`
+}
+type RevokeResult struct {
+	GrantID  string `json:"grantId"`
+	Revision uint64 `json:"grantRevision"`
+	Revoked  bool   `json:"revoked"` // R: durable tombstone, deny new admissions
+	Drained  bool   `json:"drained"` // Q: child/relay/lease/FD completion proof
+}

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

@@ -0,0 +1,51 @@
+package helper
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+	"time"
+)
+
+func TestDataContractTypes(t *testing.T) {
+	if DataProtocol != 2 || GrantSchema != 1 || MaxControlBytes != 16*1024 || MaxHealthBytes != 4096 || MaxBoundedBytes != 1<<20 {
+		t.Fatal("protocol/schema/transport ceilings changed")
+	}
+	if CandidateTTL != 60*time.Second || IntentTTL != 30*time.Second || MaxGrants != 256 || MaxPageEntries != 200 {
+		t.Fatal("consent and metadata ceilings changed")
+	}
+	if !ActionList.ReadOnly() || !ActionStat.ReadOnly() || !ActionRead.ReadOnly() || ActionCreate.ReadOnly() || ActionPublish.ReadOnly() || Action("shell").ReadOnly() {
+		t.Fatal("action classification must be closed")
+	}
+	b, err := json.Marshal(SafeError{Code: ErrDenied, OperationID: strings.Repeat("a", 64)})
+	if err != nil || strings.Contains(string(b), "path") || strings.Contains(string(b), "message") {
+		t.Fatalf("unsafe error shape: %s %v", b, err)
+	}
+	if ErrDenied.Error() != "denied" || Code("raw stderr").Valid() || Code("").Valid() {
+		t.Fatal("error set must be closed")
+	}
+}
+
+func TestGrantContinuityContract(t *testing.T) {
+	b := ContinuityBinding{Epoch: strings.Repeat("a", 64), SubjectProof: strings.Repeat("b", 64), ScopeProof: strings.Repeat("c", 64)}
+	g := Grant{State: GrantActive, LastValidated: b}
+	if g.EffectiveState(b, true) != GrantActive || g.EffectiveState(b, false) != GrantSuspended {
+		t.Fatal("unknown continuity must suspend")
+	}
+	changed := b
+	changed.Epoch = strings.Repeat("d", 64)
+	if g.EffectiveState(changed, true) != GrantSuspended {
+		t.Fatal("new epoch must suspend")
+	}
+	g.State = GrantRevoked
+	if g.EffectiveState(changed, false) != GrantRevoked {
+		t.Fatal("tombstone must remain revoked")
+	}
+	g.State = GrantSuspended
+	if g.EffectiveState(b, true) != GrantSuspended {
+		t.Fatal("continuity alone must not un-suspend")
+	}
+	if (Grant{State: GrantActive}).EffectiveState(ContinuityBinding{}, true) != GrantSuspended {
+		t.Fatal("empty proof cannot establish continuity")
+	}
+}

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

@@ -0,0 +1,184 @@
+package helper
+
+import (
+	"bytes"
+	"encoding/json"
+	"io"
+	"reflect"
+	"strings"
+	"unicode/utf8"
+)
+
+// The ordinary Go decoder accepts case aliases, duplicate keys, nulls and
+// malformed Unicode replacement. A bounded token pass rejects these first.
+func decodeDataObject(reader io.Reader, dst any, limit int) Code {
+	b, err := io.ReadAll(io.LimitReader(reader, int64(limit)+1))
+	if err != nil {
+		return ErrInvalid
+	}
+	if len(b) > limit {
+		return ErrLimit
+	}
+	if !validJSONUnicode(b) {
+		return ErrInvalid
+	}
+	d := json.NewDecoder(bytes.NewReader(b))
+	d.UseNumber()
+	if !scanDataShape(d, reflect.TypeOf(dst).Elem(), 0) {
+		return ErrInvalid
+	}
+	if _, err := d.Token(); err != io.EOF {
+		return ErrInvalid
+	}
+	d = json.NewDecoder(bytes.NewReader(b))
+	d.DisallowUnknownFields()
+	if d.Decode(dst) != nil || d.Decode(new(any)) != io.EOF {
+		return ErrInvalid
+	}
+	return ""
+}
+
+func scanDataShape(d *json.Decoder, t reflect.Type, depth int) bool {
+	if depth > 64 {
+		return false
+	}
+	for t != nil && t.Kind() == reflect.Pointer {
+		t = t.Elem()
+	}
+	if t == reflect.TypeOf(json.RawMessage{}) {
+		t = nil
+	}
+	token, err := d.Token()
+	if err != nil || token == nil {
+		return false
+	}
+	delim, container := token.(json.Delim)
+	if !container {
+		return t == nil || (t.Kind() != reflect.Struct && t.Kind() != reflect.Slice)
+	}
+	switch delim {
+	case '{':
+		if t != nil && t.Kind() != reflect.Struct {
+			return false
+		}
+		fields := map[string]reflect.Type{}
+		if t != nil {
+			for i := 0; i < t.NumField(); i++ {
+				f := t.Field(i)
+				name := strings.Split(f.Tag.Get("json"), ",")[0]
+				fields[name] = f.Type
+			}
+		}
+		seen := map[string]bool{}
+		for d.More() {
+			k, err := d.Token()
+			if err != nil {
+				return false
+			}
+			key, ok := k.(string)
+			if !ok || seen[key] {
+				return false
+			}
+			seen[key] = true
+			field, known := fields[key]
+			if t != nil && !known {
+				return false
+			}
+			if !scanDataShape(d, field, depth+1) {
+				return false
+			}
+		}
+		end, err := d.Token()
+		if err != nil || end != json.Delim('}') {
+			return false
+		}
+		if t != nil {
+			for i := 0; i < t.NumField(); i++ {
+				tag := strings.Split(t.Field(i).Tag.Get("json"), ",")
+				if len(tag) == 1 && !seen[tag[0]] {
+					return false
+				}
+			}
+		}
+		return true
+	case '[':
+		if t != nil && t.Kind() != reflect.Slice {
+			return false
+		}
+		var elem reflect.Type
+		if t != nil {
+			elem = t.Elem()
+		}
+		for d.More() {
+			if !scanDataShape(d, elem, depth+1) {
+				return false
+			}
+		}
+		end, err := d.Token()
+		return err == nil && end == json.Delim(']')
+	}
+	return false
+}
+
+func validJSONUnicode(b []byte) bool {
+	if !utf8.Valid(b) {
+		return false
+	}
+	inString := false
+	for i := 0; i < len(b); i++ {
+		if b[i] == '"' {
+			inString = !inString
+			continue
+		}
+		if !inString || b[i] != '\\' {
+			continue
+		}
+		i++
+		if i >= len(b) {
+			return false
+		}
+		if b[i] != 'u' {
+			continue
+		}
+		if i+4 >= len(b) {
+			return false
+		}
+		r, ok := unicodeEscape(b[i+1 : i+5])
+		if !ok {
+			return false
+		}
+		i += 4
+		if r >= 0xdc00 && r <= 0xdfff {
+			return false
+		}
+		if r >= 0xd800 && r <= 0xdbff {
+			if i+6 >= len(b) || b[i+1] != '\\' || b[i+2] != 'u' {
+				return false
+			}
+			low, ok := unicodeEscape(b[i+3 : i+7])
+			if !ok || low < 0xdc00 || low > 0xdfff {
+				return false
+			}
+			i += 6
+		}
+	}
+	return !inString
+}
+
+func unicodeEscape(b []byte) (uint16, bool) {
+	var r uint16
+	for _, c := range b {
+		r <<= 4
+		switch {
+		case c >= '0' && c <= '9':
+			r += uint16(c - '0')
+		case c >= 'a' && c <= 'f':
+			r += uint16(c - 'a' + 10)
+		case c >= 'A' && c <= 'F':
+			r += uint16(c - 'A' + 10)
+		default:
+			return 0, false
+		}
+	}
+	return r, true
+}

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

@@ -0,0 +1,30 @@
+package helper
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestDataDecodeOptionalStructPointersRemainStrict(t *testing.T) {
+	type child struct {
+		Value uint64 `json:"value"`
+	}
+	type envelope struct {
+		Child *child `json:"child,omitempty"`
+	}
+	for _, tc := range []struct {
+		frame string
+		want  Code
+	}{
+		{`{}`, ""}, {`{"child":{"value":1}}`, ""},
+		{`{"child":null}`, ErrInvalid}, {`{"child":{}}`, ErrInvalid},
+		{`{"child":{"value":1,"unknown":2}}`, ErrInvalid},
+		{`{"child":{"value":1,"value":2}}`, ErrInvalid},
+		{`{"Child":{"value":1}}`, ErrInvalid},
+	} {
+		var value envelope
+		if c := decodeDataObject(strings.NewReader(tc.frame), &value, MaxControlBytes); c != tc.want {
+			t.Fatalf("%s: %q want %q", tc.frame, c, tc.want)
+		}
+	}
+}