@synopackageland/cli 0.3.10 → 0.4.1

package/dist/templates/native-go/backend/internal/helper/data_protocol.go

@@ -0,0 +1,416 @@
+package helper
+
+import (
+	"bytes"
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"io"
+	"strings"
+	"sync"
+	"time"
+	"unicode/utf8"
+)
+
+type DataRequest struct {
+	Inventory     Inventory       `json:"inventory"`
+	Op            Action          `json:"op"`
+	Nonce         string          `json:"nonce"`
+	OperationID   string          `json:"operationId"`
+	Epoch         string          `json:"epoch"`
+	GrantID       string          `json:"grantId"`
+	GrantRevision uint64          `json:"grantRevision"`
+	Ticket        string          `json:"ticket"`
+	Args          json.RawMessage `json:"args"`
+}
+
+// Digest binds the entire control, including args, to a trusted single-use
+// ticket. It is not a signature or identity proof. RawMessage object order is
+// preserved; the issuer must digest the same decoded control as the consumer.
+func (r DataRequest) Digest() string {
+	b, err := json.Marshal(r)
+	if err != nil {
+		return ""
+	}
+	d := sha256.Sum256(b)
+	return hex.EncodeToString(d[:])
+}
+
+// NegotiateProtocol pins the selection to the approved inventory. Supporting
+// both versions permits legacy health only for an approved protocol 1 payload;
+// it never converts a file request or approved v2 payload into protocol 1.
+func NegotiateProtocol(offered []int, approved Inventory, files bool) (int, Code) {
+	if len(offered) == 0 || len(offered) > 2 {
+		return 0, ErrInvalid
+	}
+	seen := map[int]bool{}
+	for _, p := range offered {
+		if p != 1 && p != DataProtocol {
+			return 0, ErrIncompatible
+		}
+		if seen[p] {
+			return 0, ErrInvalid
+		}
+		seen[p] = true
+	}
+	if !approved.Valid() || (approved.Protocol != 1 && approved.Protocol != DataProtocol) || !seen[approved.Protocol] || (files && approved.Protocol != DataProtocol) {
+		return 0, ErrIncompatible
+	}
+	return approved.Protocol, ""
+}
+
+// DecodeDataRequest is bounded syntax validation, not admission. No session,
+// ACL, grant store, operation child or filesystem is accessed here.
+func DecodeDataRequest(reader io.Reader) (DataRequest, Code) {
+	var r DataRequest
+	if c := decodeDataObject(reader, &r, MaxControlBytes); c != "" {
+		return DataRequest{}, c
+	}
+	if c := validateDataRequest(r); c != "" {
+		return DataRequest{}, c
+	}
+	return r, ""
+}
+
+func validateDataRequest(r DataRequest) Code { return validateOperationRequest(r, writeGates{}) }
+func validateOperationRequest(r DataRequest, writes writeGates) Code {
+	if !r.Inventory.Valid() || r.Inventory.Protocol != DataProtocol {
+		return ErrIncompatible
+	}
+	if !allReferences(r.Nonce, r.OperationID, r.Epoch, r.GrantID, r.Ticket) || r.GrantRevision == 0 {
+		return ErrInvalid
+	}
+	var segments []string
+	var allowRoot bool
+	switch r.Op {
+	case ActionList:
+		var a ListArgs
+		if c := decodeDataObject(bytes.NewReader(r.Args), &a, MaxControlBytes); c != "" {
+			return c
+		}
+		if a.Limit == 0 {
+			return ErrInvalid
+		}
+		if a.Limit > MaxPageEntries {
+			return ErrLimit
+		}
+		if a.Cursor != "" && !digestPattern.MatchString(a.Cursor) {
+			return ErrInvalid
+		}
+		segments, allowRoot = a.Segments, true
+	case ActionStat:
+		var a StatArgs
+		if c := decodeDataObject(bytes.NewReader(r.Args), &a, MaxControlBytes); c != "" {
+			return c
+		}
+		segments, allowRoot = a.Segments, true
+	case ActionRead, ActionReadStream:
+		var a ReadArgs
+		if c := decodeDataObject(bytes.NewReader(r.Args), &a, MaxControlBytes); c != "" {
+			return c
+		}
+		if a.MaxBytes == 0 {
+			return ErrInvalid
+		}
+		ceiling := uint64(MaxBoundedBytes)
+		if r.Op == ActionReadStream {
+			ceiling = MaxTransferBytes
+		}
+		if a.MaxBytes > ceiling {
+			return ErrLimit
+		}
+		segments = a.Segments
+	case ActionCreate:
+		var a CreateArgs
+		if c := decodeDataObject(bytes.NewReader(r.Args), &a, MaxControlBytes); c != "" {
+			return c
+		}
+		if !a.Exclusive {
+			return ErrInvalid
+		}
+		if a.Bytes > MaxBoundedBytes {
+			return ErrLimit
+		}
+		if c := ValidateRelativeSegments(a.Segments, false); c != "" {
+			return c
+		}
+		if !writes.allows(r.Op) {
+			return ErrUnsupported
+		}
+		if a.Bytes == 0 {
+			return ErrLimit
+		}
+		return ""
+	case ActionWriteStream:
+		var a WriteStreamArgs
+		if c := decodeDataObject(bytes.NewReader(r.Args), &a, MaxControlBytes); c != "" {
+			return c
+		}
+		if a.MaxBytes == 0 {
+			return ErrInvalid
+		}
+		if a.MaxBytes > MaxTransferBytes {
+			return ErrLimit
+		}
+		if c := ValidateRelativeSegments(a.Segments, false); c != "" {
+			return c
+		}
+		if !writes.allows(r.Op) {
+			return ErrUnsupported
+		}
+		return ""
+	case ActionPublish:
+		var a PublishArgs
+		if c := decodeDataObject(bytes.NewReader(r.Args), &a, MaxControlBytes); c != "" {
+			return c
+		}
+		if !a.NoOverwrite || !digestPattern.MatchString(a.StageID) {
+			return ErrInvalid
+		}
+		if !writes.allows(r.Op) {
+			return ErrUnsupported
+		}
+		return ""
+	default:
+		return ErrUnsupported
+	}
+	return ValidateRelativeSegments(segments, allowRoot)
+}
+
+// JSON carries literal UTF-8 segments, never a URL-encoded path. No Clean,
+// unescape, Unicode normalization or path-prefix authorization is performed.
+func ValidateRelativeSegments(segments []string, allowRoot bool) Code {
+	if len(segments) > MaxPathSegments {
+		return ErrLimit
+	}
+	if segments == nil || (!allowRoot && len(segments) == 0) {
+		return ErrInvalid
+	}
+	total := 0
+	for i, s := range segments {
+		if len(s) > MaxSegmentBytes {
+			return ErrLimit
+		}
+		if s == "" || s == "." || s == ".." || !utf8.ValidString(s) || strings.ContainsAny(s, "/\\\x00") {
+			return ErrInvalid
+		}
+		total += len(s)
+		if i > 0 {
+			total++
+		}
+		if total > MaxPathBytes {
+			return ErrLimit
+		}
+	}
+	return ""
+}
+
+// TicketBinding may only be constructed by the future trusted S1 validator.
+// In particular, package UID, opaque IDs and caller-supplied principal fields
+// do not establish identity. This binding stays in deadline-bounded memory.
+type TicketBinding struct {
+	Inventory                                 Inventory
+	Epoch, SubjectRef, SessionRef             string
+	Action                                    Action
+	GrantID                                   string
+	GrantRevision                             uint64
+	OperationID, Nonce, Ticket, RequestDigest string
+	ExpiresAt                                 time.Time
+}
+
+// ReplayWindow is a contract fixture primitive for one validated native
+// session in one epoch. The admission owner must retain exactly one window
+// for that binding; it must never replace a full window to bypass replay.
+// S2/S3 must integrate consumption at their common admission ordering point.
+type ReplayWindow struct {
+	mu                          sync.Mutex
+	inventory                   Inventory
+	epoch, subject, session     string
+	nonces, operations, tickets map[string]bool
+}
+
+func NewReplayWindow(i Inventory, epoch, subject, session string) (*ReplayWindow, Code) {
+	if !i.Valid() || i.Protocol != DataProtocol {
+		return nil, ErrIncompatible
+	}
+	if !allReferences(epoch, subject, session) {
+		return nil, ErrInvalid
+	}
+	return &ReplayWindow{inventory: i, epoch: epoch, subject: subject, session: session, nonces: map[string]bool{}, operations: map[string]bool{}, tickets: map[string]bool{}}, ""
+}
+
+func (w *ReplayWindow) Consume(r DataRequest, b TicketBinding, now time.Time) Code {
+	if w == nil || w.nonces == nil {
+		return ErrIncompatible
+	}
+	if c := validateDataRequest(r); c != "" {
+		return c
+	}
+	if r.Inventory != w.inventory || b.Inventory != w.inventory {
+		return ErrIncompatible
+	}
+	if r.Epoch != w.epoch || b.Epoch != w.epoch {
+		return ErrStale
+	}
+	if b.SubjectRef != w.subject || b.SessionRef != w.session || b.Action != r.Op || b.GrantID != r.GrantID || b.GrantRevision != r.GrantRevision || b.OperationID != r.OperationID || b.Nonce != r.Nonce || b.Ticket != r.Ticket || b.RequestDigest != r.Digest() {
+		return ErrDenied
+	}
+	if !now.Before(b.ExpiresAt) {
+		return ErrExpired
+	}
+	if b.ExpiresAt.Sub(now) > IntentTTL {
+		return ErrInvalid
+	}
+	w.mu.Lock()
+	defer w.mu.Unlock()
+	if w.nonces[r.Nonce] || w.operations[r.OperationID] || w.tickets[r.Ticket] {
+		return ErrReplay
+	}
+	if len(w.nonces) >= MaxReplayEntries {
+		return ErrBusy
+	}
+	w.nonces[r.Nonce] = true
+	w.operations[r.OperationID] = true
+	w.tickets[r.Ticket] = true
+	return ""
+}
+
+func DecodeGrantStore(reader io.Reader) (GrantStore, Code) {
+	var s GrantStore
+	if c := decodeDataObject(reader, &s, MaxGrantStoreBytes); c != "" {
+		return GrantStore{}, c
+	}
+	if s.Schema != GrantSchema || s.Revision == 0 || s.Grants == nil {
+		return GrantStore{}, ErrInvalid
+	}
+	if len(s.Grants) > MaxGrants {
+		return GrantStore{}, ErrLimit
+	}
+	seen := map[string]bool{}
+	for _, g := range s.Grants {
+		if c := validateGrant(g); c != "" {
+			return GrantStore{}, c
+		}
+		if seen[g.ID] {
+			return GrantStore{}, ErrInvalid
+		}
+		seen[g.ID] = true
+	}
+	return s, ""
+}
+
+func validateGrant(g Grant) Code {
+	if g.Schema != GrantSchema || g.Revision == 0 || !allReferences(g.ID, g.ApprovalBinding, g.CapabilityDigest) || g.CreatedAt <= 0 {
+		return ErrInvalid
+	}
+	if !g.Inventory.Valid() || g.Inventory.Protocol != DataProtocol {
+		return ErrIncompatible
+	}
+	if !validPrincipal(g.Owner) || !validPrincipal(g.Issuer) || !validContinuity(g.LastValidated) {
+		return ErrInvalid
+	}
+	if g.Owner.IdentityBasis == "uid-username" || g.Issuer.IdentityBasis == "uid-username" {
+		if g.Inventory.DataAccess != "relaxed" || g.Owner.IdentityBasis != "uid-username" || g.Issuer.IdentityBasis != "uid-username" {
+			return ErrInvalid
+		}
+	}
+	if g.Scope.Kind != ScopeShared && g.Scope.Kind != ScopePersonal {
+		return ErrInvalid
+	}
+	if g.Scope.TargetKind != "directory" || !allReferences(g.Scope.AnchorRef, g.Scope.ObjectRef, g.Scope.MountRef) {
+		return ErrInvalid
+	}
+	if g.Scope.Kind == ScopePersonal && g.Owner != g.Issuer {
+		return ErrDenied
+	}
+	if c := ValidateRelativeSegments(g.Scope.Segments, g.Scope.Kind == ScopeShared); c != "" {
+		return c
+	}
+	if c := validateGrantActions(g.Actions); c != "" {
+		return c
+	}
+	switch g.State {
+	case GrantActive:
+		if g.RevokedAt != 0 || g.Reason != "" {
+			return ErrInvalid
+		}
+	case GrantSuspended:
+		if g.RevokedAt != 0 || !g.Reason.Valid() {
+			return ErrInvalid
+		}
+	case GrantRevoked:
+		if g.RevokedAt < g.CreatedAt || !g.Reason.Valid() {
+			return ErrInvalid
+		}
+	default:
+		return ErrInvalid
+	}
+	return ""
+}
+
+func DecodeIntent(reader io.Reader) (Intent, Code) {
+	var i Intent
+	if c := decodeDataObject(reader, &i, MaxControlBytes); c != "" {
+		return Intent{}, c
+	}
+	if !i.Inventory.Valid() || i.Inventory.Protocol != DataProtocol {
+		return Intent{}, ErrIncompatible
+	}
+	if !allReferences(i.ID, i.Epoch, i.SubjectRef, i.SessionRef, i.CandidateID, i.SummaryDigest) || i.ExpiresAt <= 0 || (i.ScopeKind != ScopeShared && i.ScopeKind != ScopePersonal) {
+		return Intent{}, ErrInvalid
+	}
+	if c := validateGrantActions(i.Actions); c != "" {
+		return Intent{}, c
+	}
+	return i, ""
+}
+
+func validateGrantActions(actions []Action) Code {
+	if len(actions) == 0 || len(actions) > 7 {
+		return ErrInvalid
+	}
+	seen := map[Action]bool{}
+	for _, a := range actions {
+		if !a.ReadOnly() && a != ActionCreate && a != ActionWriteStream && a != ActionPublish {
+			return ErrUnsupported
+		}
+		if seen[a] {
+			return ErrInvalid
+		}
+		seen[a] = true
+	}
+	return ""
+}
+func allReferences(refs ...string) bool {
+	for _, r := range refs {
+		if !digestPattern.MatchString(r) {
+			return false
+		}
+	}
+	return true
+}
+func validPrincipal(p Principal) bool {
+	if p.Kind != "local" || !allReferences(p.SubjectRef, p.InstanceRef) {
+		return false
+	}
+	if p.IdentityBasis == "" {
+		return p.UID == 0 && p.Username == ""
+	}
+	return p.IdentityBasis == "uid-username" && validRelaxedIdentity(RelaxedIdentity{p.UID, p.Username})
+}
+func validContinuity(b ContinuityBinding) bool {
+	return allReferences(b.Epoch, b.SubjectProof, b.ScopeProof)
+}
+
+// MarshalJSON prevents an accidentally propagated native error string from
+// becoming a wire code or operation ID. Paths/messages have no field here.
+func (e SafeError) MarshalJSON() ([]byte, error) {
+	if !e.Code.Valid() {
+		e.Code = ErrInternal
+	}
+	if e.OperationID != "" && !digestPattern.MatchString(e.OperationID) {
+		e.OperationID = ""
+	}
+	type safe SafeError
+	return json.Marshal(safe(e))
+}