@synopackageland/cli 0.4.0 → 0.5.0

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

@@ -0,0 +1,40 @@
+package helper
+
+import (
+	"context"
+	"time"
+)
+
+// Stream is a staged fixed read action. It has no public socket/generator/CGI
+// enablement until DSM FD ACL and end-to-end CGI proof pass.
+const MaxStreamReplayEntries = MaxPackageOperations * (MaxTransferBytes/MaxChunkBytes + MaxReplayEntries)
+
+func readDataCeiling(a Action) uint64 {
+	if a == ActionReadStream {
+		return MaxTransferBytes
+	}
+	return MaxBoundedBytes
+}
+func (op *cohortOperation) expired(now time.Time) bool {
+	if op.admittedAt.IsZero() {
+		return false
+	}
+	stream := op.work != nil && op.work.Action == ActionReadStream || op.writeWork != nil && op.writeWork.Action == ActionWriteStream
+	if !stream {
+		return now.Sub(op.admittedAt) >= BoundedTimeout
+	}
+	last := op.lastActivity
+	if last.IsZero() {
+		last = op.admittedAt
+	}
+	return now.Before(op.admittedAt) || now.Before(last) || now.Sub(op.admittedAt) >= StreamTotalTimeout || now.Sub(last) >= StreamIdleTimeout
+}
+
+// Internal child stream interface. Only a fixed actor-opened FD implementation
+// is constructed by bootstrap. Caller transport supplies leases, never a source.
+// A successful chunk includes fresh child FD ACL/object checks. Root separately
+// binds subject/session/ticket/grant/revision/epoch under the S3 admission lock.
+type readStreamSource interface {
+	ReadChunk(context.Context, uint32) ([]byte, Code)
+	Close()
+}

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

@@ -0,0 +1,109 @@
+package helper
+
+import (
+	"context"
+	"golang.org/x/sys/unix"
+	"io"
+)
+
+// Child-only FD source. Bounded reads retain S5's eager validation/buffer;
+// streams retain the captured object and allocate at most one leased chunk.
+// No caller path, range, URL, executable, or root-opened readable FD is accepted.
+type actorReadTransfer struct {
+	ctx               context.Context
+	object            *readOnlyObject
+	work              readOnlyWork
+	acl               readOnlyACL
+	buffer            []byte
+	remaining, offset uint64
+}
+
+func openActorReadTransfer(ctx context.Context, pin *pinnedReadOnlyRoot, w readOnlyWork, acl readOnlyACL) (*actorReadTransfer, readOnlyResult) {
+	fail := func(c Code) (*actorReadTransfer, readOnlyResult) { return nil, readOnlyResult{Code: c} }
+	if code := w.validate(); code != "" {
+		return fail(code)
+	}
+	if w.Action != ActionRead && w.Action != ActionReadStream {
+		return fail(ErrUnsupported)
+	}
+	if acl == nil {
+		return fail(ErrUnsupported)
+	}
+	o, code := resolveReadOnly(ctx, pin, w)
+	if code != "" {
+		return fail(code)
+	}
+	ok := false
+	defer func() {
+		if !ok {
+			o.Close()
+		}
+	}()
+	if code := authorizeReadOnly(ctx, o, w, acl); code != "" {
+		return fail(code)
+	}
+	if o.before.Mode&unix.S_IFMT != unix.S_IFREG {
+		return fail(ErrDenied)
+	}
+	if o.before.Size < 0 || uint64(o.before.Size) > w.MaxBytes {
+		return fail(ErrLimit)
+	}
+	src := &actorReadTransfer{ctx: ctx, object: o, work: w, acl: acl, remaining: uint64(o.before.Size)}
+	if w.Action == ActionRead {
+		b, err := io.ReadAll(io.LimitReader(o.data, int64(w.MaxBytes)+1))
+		if err != nil {
+			return fail(readOnlyError(err))
+		}
+		if uint64(len(b)) > w.MaxBytes {
+			return fail(ErrLimit)
+		}
+		if uint64(len(b)) != src.remaining {
+			return fail(ErrStale)
+		}
+		src.buffer = b
+	}
+	if code := src.check(); code != "" {
+		return fail(code)
+	}
+	ok = true
+	return src, readOnlyResult{Bytes: src.remaining}
+}
+func (s *actorReadTransfer) check() Code {
+	if code := authorizeReadOnly(s.ctx, s.object, s.work, s.acl); code != "" {
+		return code
+	}
+	return readOnlyUnchanged(int(s.object.data.Fd()), s.object.before)
+}
+func (s *actorReadTransfer) Next(n uint32) ([]byte, Code) {
+	if n == 0 || n > MaxChunkBytes || uint64(n) > s.remaining {
+		return nil, ErrLimit
+	}
+	if code := s.check(); code != "" {
+		return nil, code
+	}
+	var b []byte
+	if s.work.Action == ActionRead {
+		b = s.buffer[s.offset : s.offset+uint64(n)]
+	} else {
+		b = make([]byte, n)
+		if _, err := io.ReadFull(s.object.data, b); err != nil {
+			return nil, ErrStale
+		}
+	}
+	if code := s.check(); code != "" {
+		return nil, code
+	}
+	s.remaining -= uint64(n)
+	s.offset += uint64(n)
+	return b, ""
+}
+func (s *actorReadTransfer) Close() { s.object.Close(); s.buffer = nil }
+
+var _ readStreamSource = (*actorReadTransfer)(nil)
+
+func (s *actorReadTransfer) ReadChunk(ctx context.Context, n uint32) ([]byte, Code) {
+	original := s.ctx
+	s.ctx = ctx
+	defer func() { s.ctx = original }()
+	return s.Next(n)
+}

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

@@ -0,0 +1,118 @@
+package helper
+
+import (
+	"bytes"
+	"context"
+	"io"
+	"os"
+	"testing"
+)
+
+func TestActorReadStreamChunkACLAndChange(t *testing.T) {
+	for _, kind := range []string{"valid", "acl", "replacement", "hardlink", "mutation", "oversize", "cancel"} {
+		t.Run(kind, func(t *testing.T) {
+			pin, root := readOnlyFixture(t)
+			data := bytes.Repeat([]byte("z"), 2*MaxChunkBytes)
+			os.WriteFile(root+"/file", data, 0644)
+			acl := &changingTransferACL{}
+			ctx, cancel := context.WithCancel(context.Background())
+			defer cancel()
+			w := readWork(pin, "file")
+			w.Action = ActionReadStream
+			w.MaxBytes = MaxTransferBytes
+			src, result := openActorReadTransfer(ctx, pin, w, acl)
+			if result.Code != "" || src == nil || result.Bytes != uint64(len(data)) {
+				t.Fatal(result)
+			}
+			defer src.Close()
+			b, code := src.Next(MaxChunkBytes)
+			if code != "" || len(b) != MaxChunkBytes {
+				t.Fatal(code)
+			}
+			switch kind {
+			case "acl":
+				acl.deny = true
+			case "replacement":
+				os.Rename(root+"/file", root+"/old")
+				os.WriteFile(root+"/file", data, 0644)
+			case "hardlink":
+				os.Link(root+"/file", root+"/alias")
+			case "mutation":
+				os.WriteFile(root+"/file", data[:1], 0644)
+			case "cancel":
+				cancel()
+			}
+			n := uint32(MaxChunkBytes)
+			if kind == "oversize" {
+				n++
+			}
+			b, code = src.Next(n)
+			if kind == "valid" {
+				if code != "" || len(b) != MaxChunkBytes || acl.calls < 6 {
+					t.Fatal(code, acl.calls)
+				}
+			} else if code == "" || len(b) != 0 {
+				t.Fatal("unproved chunk escaped", code, len(b))
+			}
+		})
+	}
+}
+
+type changingTransferACL struct {
+	deny  bool
+	calls int
+}
+
+func (a *changingTransferACL) Authorize(context.Context, Action, int) Code {
+	a.calls++
+	if a.deny {
+		return ErrDenied
+	}
+	return ""
+}
+
+func TestActorReadStreamMaximumHasNoWholeFileBuffer(t *testing.T) {
+	pin, root := readOnlyFixture(t)
+	f, e := os.Create(root + "/maximum")
+	if e != nil {
+		t.Fatal(e)
+	}
+	if e = f.Truncate(MaxTransferBytes); e != nil {
+		t.Fatal(e)
+	}
+	f.Close()
+	w := readWork(pin, "maximum")
+	w.Action = ActionReadStream
+	w.MaxBytes = MaxTransferBytes
+	ctx, cancel := context.WithTimeout(context.Background(), StreamTotalTimeout)
+	defer cancel()
+	src, result := openActorReadTransfer(ctx, pin, w, fixtureReadOnlyACL{})
+	if result.Code != "" || src == nil || src.buffer != nil || result.Bytes != MaxTransferBytes {
+		t.Fatal(result)
+	}
+	defer src.Close()
+	for n := 0; n < MaxTransferBytes/MaxChunkBytes; n++ {
+		b, code := src.Next(MaxChunkBytes)
+		if code != "" || len(b) != MaxChunkBytes {
+			t.Fatal(n, code)
+		}
+	}
+	if _, code := src.Next(1); code != ErrLimit {
+		t.Fatal("read beyond transfer ceiling", code)
+	}
+}
+
+func TestReadStreamOutputWatchErrorSurvivesSuccessfulChunk(t *testing.T) {
+	p := newLinuxOperationRelay(nil, nil, nil, nil)
+	p.outputWatch = make(chan error, 1)
+	p.outputWatchDone = false
+	p.outputWatch <- io.ErrClosedPipe
+	p.pending = make(chan operationRelayOutcome, 1)
+	p.pending <- operationRelayOutcome{}
+	if _, err := p.idle(); err == nil {
+		t.Fatal("successful chunk erased disconnect")
+	}
+	if _, err := p.idle(); err == nil {
+		t.Fatal("disconnect observation lost")
+	}
+}

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

@@ -0,0 +1,177 @@
+package helper
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"syscall"
+	"testing"
+	"time"
+)
+
+func TestReadStreamControlCeilings(t *testing.T) {
+	s, repo, _, _, g, _ := grantCohortFixture(t)
+	_ = s
+	repo.store.Grants[0].Actions = []Action{ActionReadStream}
+	r := grantControl(t, g, '1', '2', '3', MaxTransferBytes)
+	r.Op = ActionReadStream
+	b, _ := json.Marshal(r)
+	if _, c := DecodeDataRequest(bytes.NewReader(b)); c != "" {
+		t.Fatal(c)
+	}
+	r.Args = []byte(`{"segments":["fixture"],"maxBytes":67108865}`)
+	b, _ = json.Marshal(r)
+	if _, c := DecodeDataRequest(bytes.NewReader(b)); c != ErrLimit {
+		t.Fatal(c)
+	}
+	r.Op = ActionRead
+	b, _ = json.Marshal(r)
+	if _, c := DecodeDataRequest(bytes.NewReader(b)); c == "" {
+		t.Fatal("bounded mode accepted stream ceiling")
+	}
+}
+func TestReadStreamIdleAndTotalDeadline(t *testing.T) {
+	now := time.Now()
+	op := &cohortOperation{work: &readOnlyWork{Action: ActionReadStream}, admittedAt: now, lastActivity: now}
+	if op.expired(now.Add(StreamIdleTimeout - time.Nanosecond)) {
+		t.Fatal("early timeout")
+	}
+	if !op.expired(now.Add(StreamIdleTimeout)) {
+		t.Fatal("idle ignored")
+	}
+	op.lastActivity = now.Add(StreamTotalTimeout - time.Second)
+	if !op.expired(now.Add(StreamTotalTimeout)) {
+		t.Fatal("total ignored")
+	}
+}
+func TestReadStreamFreshGrantProofEveryChunk(t *testing.T) {
+	for _, kind := range []string{"valid", "acl", "groups", "epoch", "replay", "R", "busy"} {
+		t.Run(kind, func(t *testing.T) {
+			s, repo, c, carriers, g, _ := grantCohortFixture(t)
+			repo.store.Grants[0].Actions = []Action{ActionReadStream}
+			p := &metadataProcessStub{operationFixture: &operationFixture{}, result: &readOnlyResult{Bytes: 2 * MaxChunkBytes}, released: true}
+			c.startChild = func(NativeActor, operationBinding) (operationProcess, error) { return p, nil }
+			r := grantControl(t, g, '1', '2', '3', 2*MaxChunkBytes)
+			r.Op = ActionReadStream
+			if code := s.start(context.Background(), operationPeer{42, 0}, carriers, r); code != "" {
+				t.Fatal(code)
+			}
+			chunk := grantControl(t, g, '1', '4', '5', MaxChunkBytes)
+			chunk.Op = ActionReadStream
+			if code := s.chunk(context.Background(), operationPeer{42, 0}, carriers, chunk); code != "" {
+				t.Fatal(code)
+			}
+			p.pending = false
+			chunk.Nonce = grantRef('6')
+			chunk.Ticket = grantRef('7')
+			switch kind {
+			case "acl":
+				s.services.operations = grantOperationStub{code: ErrDenied}
+			case "groups":
+				c.operations[r.OperationID].actor.account.Groups = []uint32{999}
+			case "epoch":
+				chunk.Epoch = grantRef('f')
+			case "replay":
+				chunk.Nonce = grantRef('4')
+				chunk.Ticket = grantRef('5')
+			case "R":
+				repo.store.Grants[0].State = GrantRevoked
+				repo.store.Grants[0].Revision++
+				repo.store.Grants[0].RevokedAt = g.CreatedAt
+				repo.store.Grants[0].Reason = ErrRevoked
+			case "busy":
+				p.pending = true
+			}
+			code := s.chunk(context.Background(), operationPeer{42, 0}, carriers, chunk)
+			if kind == "valid" {
+				if code != "" || c.operations[r.OperationID].bytes != 2*MaxChunkBytes {
+					t.Fatal(code)
+				}
+			} else if code == "" || c.operations[r.OperationID].bytes != MaxChunkBytes {
+				t.Fatal("invalid lease admitted", code)
+			}
+		})
+	}
+}
+
+func TestStreamTicketWindowDoesNotTruncateAtBoundedReadWindow(t *testing.T) {
+	s, repo, _, carriers, g, _ := grantCohortFixture(t)
+	repo.store.Grants[0].Actions = []Action{ActionReadStream}
+	a, code := s.authority.actor(context.Background(), carriers, nil)
+	if code != "" {
+		t.Fatal(code)
+	}
+	for i := 0; i < MaxTransferBytes/MaxChunkBytes+1; i++ {
+		r := grantControl(t, g, '1', '2', '3', MaxChunkBytes)
+		r.Op = ActionReadStream
+		r.Nonce = fmt.Sprintf("%064x", i+1)
+		r.Ticket = fmt.Sprintf("%064x", i+10000)
+		proof, code := (grantOperationStub{}).ValidateOperation(context.Background(), a, r, g)
+		if code != "" {
+			t.Fatal(code)
+		}
+		if code = s.ticketLocked(r, proof.Ticket, a); code != "" {
+			t.Fatal(i, code)
+		}
+		s.burnTicket(r)
+		if code = s.ticketLocked(r, proof.Ticket, a); code != ErrReplay {
+			t.Fatal(i, code)
+		}
+	}
+}
+
+type relayFailureFixture struct{ *operationFixture }
+
+func (p relayFailureFixture) idle() (bool, error) { return true, io.ErrClosedPipe }
+func TestCohortPollCancelsDisconnectedOutput(t *testing.T) {
+	c, _, _, a, b, _ := cohortFixture(t)
+	f := &operationFixture{childFixture: childFixture{exitOn: syscall.SIGKILL}}
+	op := &cohortOperation{binding: b, actor: a, process: relayFailureFixture{f}, admittedAt: c.now()}
+	c.operations[b.OperationID] = op
+	c.started = 1
+	if err := c.poll(); err != nil {
+		t.Fatal(err)
+	}
+	if !op.canceled || !f.stopped {
+		t.Fatal("disconnected client retained live transfer")
+	}
+	if err := c.poll(); err != nil {
+		t.Fatal(err)
+	}
+	if len(c.operations) != 0 || c.reaped != 1 {
+		t.Fatal("disconnect did not reach observed quiescence")
+	}
+}
+
+func TestTransferSubjectFreshnessIncludesSessionObservation(t *testing.T) {
+	p, s, _, carriers, now := nativeFixture()
+	s.value.CheckedAt = now.Add(-NativeProofFreshness / 2)
+	a, code := p.Resolve(context.Background(), carriers)
+	if code != "" {
+		t.Fatal(code)
+	}
+	if !a.account.CheckedAt.Equal(s.value.CheckedAt) {
+		t.Fatal("transfer extended older session proof", a.account.CheckedAt, s.value.CheckedAt)
+	}
+}
+
+func TestReadStreamServerIssuedWindowCompletesMaximumTransfer(t *testing.T) {
+	tickets, actor, request, _ := deliveryFixture(t)
+	request.Op = ActionReadStream
+	for i := 0; i < MaxTransferBytes/MaxChunkBytes+1; i++ {
+		request.Nonce = fmt.Sprintf("%064x", i+10000)
+		issued, code := tickets.issue(context.Background(), actor, request)
+		if code != "" {
+			t.Fatal(i, code)
+		}
+		if _, code = tickets.consume(context.Background(), actor, issued); code != "" {
+			t.Fatal(i, code)
+		}
+	}
+	request.Op = ActionRead
+	if _, code := tickets.issue(context.Background(), actor, request); code != "" {
+		t.Fatal("stream consumed independent bounded window", code)
+	}
+}

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

@@ -0,0 +1,105 @@
+package helper
+
+import (
+	"context"
+	"strings"
+)
+
+// Fixed internal work, assembled only by the trusted supervisor. Never accept
+// RootPath or descriptors from package/browser RPC. Grant admission stays S3-owned.
+type readOnlyWork struct {
+	RootPath string   `json:"rootPath"`
+	Action   Action   `json:"action"`
+	Segments []string `json:"segments"`
+	MaxBytes uint64   `json:"maxBytes"`
+	Limit    uint32   `json:"limit"`
+}
+
+type readOnlyResult struct {
+	Mutation *MutationReceipt `json:"mutation,omitempty"`
+	Code     Code             `json:"code"`
+	Entry    *Entry           `json:"entry,omitempty"`
+	List     *ListResult      `json:"list,omitempty"`
+	Bytes    uint64           `json:"bytes"`
+}
+
+// Mandatory child-side native share/home and action ACL adapter. Unknown native
+// semantics MUST refuse; syscall success cannot substitute for DSM share gates.
+// fd is an actor-opened object, never a caller path or root-opened readable FD.
+// No adapter is installed in shipped binaries until separate DSM proof passes.
+type readOnlyACL interface {
+	Authorize(context.Context, Action, int) Code
+}
+
+func (w readOnlyWork) validate() Code {
+	if !strings.HasPrefix(w.RootPath, "/") || w.RootPath == "/" {
+		return ErrInvalid
+	}
+	if code := ValidateRelativeSegments(strings.Split(w.RootPath[1:], "/"), false); code != "" {
+		return code
+	}
+	if !w.Action.ReadOnly() {
+		return ErrUnsupported
+	}
+	if code := ValidateRelativeSegments(w.Segments, w.Action != ActionRead && w.Action != ActionReadStream); code != "" {
+		return code
+	}
+	switch w.Action {
+	case ActionRead, ActionReadStream:
+		if w.MaxBytes == 0 || w.MaxBytes > readDataCeiling(w.Action) || w.Limit != 0 {
+			return ErrLimit
+		}
+	case ActionList:
+		if w.Limit == 0 || w.Limit > MaxPageEntries || w.MaxBytes != 0 {
+			return ErrLimit
+		}
+	case ActionStat:
+		if w.Limit != 0 || w.MaxBytes != 0 {
+			return ErrInvalid
+		}
+	}
+	return ""
+}
+
+// Private child metadata; bulk data only traverses the inherited leased pipe.
+type readOnlyPacket struct {
+	Binding       operationBinding `json:"binding"`
+	Token         string           `json:"token"`
+	Result        *readOnlyResult  `json:"result,omitempty"`
+	MountFD       *uint32          `json:"mountFd,omitempty"`
+	ChunkSequence uint64           `json:"chunkSequence,omitempty"`
+	MountSequence uint64           `json:"mountSequence,omitempty"`
+}
+type readOnlyMountReply struct {
+	Token    string `json:"token"`
+	Sequence uint64 `json:"sequence"`
+	Mount    uint64 `json:"mount"`
+	Code     Code   `json:"code"`
+}
+type readOnlyPacketOutcome struct {
+	result        *readOnlyResult
+	err           error
+	mountSequence uint64
+}
+
+func (r readOnlyResult) validFor(w readOnlyWork) bool {
+	if r.Mutation != nil {
+		return false
+	}
+	if r.Code != "" {
+		return r.Code.Valid() && r.Bytes == 0 && r.Entry == nil && r.List == nil
+	}
+	switch w.Action {
+	case ActionRead, ActionReadStream:
+		return r.Bytes <= w.MaxBytes && r.Entry == nil && r.List == nil
+	case ActionStat:
+		return r.Bytes == 0 && r.Entry != nil && r.List == nil
+	case ActionList:
+		return r.Bytes == 0 && r.Entry == nil && r.List != nil && len(r.List.Entries) <= int(w.Limit) && r.List.Cursor == ""
+	}
+	return false
+}
+
+type operationReadOnlyFinish struct {
+	Token string `json:"token"`
+}

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

@@ -0,0 +1,85 @@
+package helper
+
+import (
+	"encoding/json"
+	"slices"
+)
+
+// Private epoch-live capability, supplied by the fixed S3 operation validator.
+// It is not serialized into grant storage or caller controls. On Linux the only
+// concrete production witness accepted by the child factory is an O_PATH pin.
+type readOnlyRootWitness interface {
+	readOnlyRootPath() string
+	sameReadOnlyRoot(readOnlyRootWitness) bool
+}
+type readOnlyMetadataProcess interface {
+	readOnlyMetadata() (*readOnlyResult, bool, error)
+	releaseReadOnlyMetadata() error
+	readOnlyLeaseReady(uint32) Code
+}
+
+func readOnlyRequestWork(r DataRequest, root readOnlyRootWitness) (*readOnlyWork, Code) {
+	w := &readOnlyWork{Action: r.Op}
+	if root != nil {
+		w.RootPath = root.readOnlyRootPath()
+	}
+	switch r.Op {
+	case ActionRead, ActionReadStream:
+		var a ReadArgs
+		if code := decodeDataObject(bytesReader(r.Args), &a, MaxControlBytes); code != "" {
+			return nil, code
+		}
+		w.Segments = slices.Clone(a.Segments)
+		w.MaxBytes = a.MaxBytes
+	case ActionStat:
+		var a StatArgs
+		if code := decodeDataObject(bytesReader(r.Args), &a, MaxControlBytes); code != "" {
+			return nil, code
+		}
+		w.Segments = slices.Clone(a.Segments)
+	case ActionList:
+		var a ListArgs
+		if code := decodeDataObject(bytesReader(r.Args), &a, MaxControlBytes); code != "" {
+			return nil, code
+		}
+		if a.Cursor != "" {
+			return nil, ErrUnsupported
+		}
+		w.Segments = slices.Clone(a.Segments)
+		w.Limit = a.Limit
+	default:
+		return nil, ErrUnsupported
+	}
+	// Unit-test S3 synthetic factories have no root. The actual Linux factory
+	// always refuses nil; production has no native/ACL adapter installed.
+	if root != nil {
+		if code := w.validate(); code != "" {
+			return nil, code
+		}
+	}
+	return w, ""
+}
+func sameReadOnlyRequest(op *cohortOperation, w *readOnlyWork, root readOnlyRootWitness, metadata bool) bool {
+	if op.work == nil || op.work.Action != w.Action || !slices.Equal(op.work.Segments, w.Segments) || op.work.Limit != w.Limit {
+		return false
+	}
+	if op.root == nil {
+		if root != nil {
+			return false
+		}
+	} else if root == nil || !op.root.sameReadOnlyRoot(root) {
+		return false
+	}
+	return !metadata || op.work.MaxBytes == w.MaxBytes
+}
+func cloneReadOnlyResult(r *readOnlyResult) *readOnlyResult {
+	b, err := json.Marshal(r)
+	if err != nil {
+		return nil
+	}
+	var result readOnlyResult
+	if json.Unmarshal(b, &result) != nil {
+		return nil
+	}
+	return &result
+}