@synopackageland/cli 0.4.0 → 0.4.1

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

@@ -0,0 +1,516 @@
+package helper
+
+import (
+	"context"
+	"crypto/rand"
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"math"
+	"slices"
+	"sync"
+	"time"
+)
+
+type pendingConsent struct {
+	intent    Intent
+	actor     NativeActor
+	selection ConsentSelection
+}
+
+// GrantAuthority is one supervisor's ordering owner. All reservations, confirms,
+// revokes and Fence calls use this order. Native/ACL observations and cohort
+// drain happen outside it. There is no process-global or helper RPC wiring yet.
+type GrantAuthority struct {
+	mu         *sync.Mutex
+	gate       *admission
+	repository GrantRepository
+	native     *NativeProvider
+	consent    ConsentValidator
+	cohort     GrantCohort
+	policy     GrantPolicy
+	writes     writeGates
+	fenced     bool
+	intents    map[string]pendingConsent
+	now        func() time.Time
+}
+
+// NewGrantAuthority reconciles before any admission, even when epoch/approval
+// bytes match. Restart cannot prove account/scope continuity. There is no API
+// to reactivate a suspended record or remove a tombstone; consent creates an ID.
+func NewGrantAuthority(repository GrantRepository, native *NativeProvider, consent ConsentValidator, cohort GrantCohort) (*GrantAuthority, Code) {
+	if repository == nil {
+		return nil, ErrUnavailable
+	}
+	a := &GrantAuthority{mu: &sync.Mutex{}, repository: repository, native: native, consent: consent, cohort: cohort, intents: map[string]pendingConsent{}, now: time.Now}
+	c := repository.Transact(func(p GrantPolicy, s *GrantStore) (bool, Code) {
+		if !validGrantPolicy(p) {
+			return false, ErrIncompatible
+		}
+		a.policy = p
+		a.fenced = !p.Enabled
+		changed := false
+		for n := range s.Grants {
+			g := &s.Grants[n]
+			if g.State == GrantActive {
+				if g.Revision == math.MaxUint64 {
+					return false, ErrLimit
+				}
+				g.State = GrantSuspended
+				g.Reason = ErrSuspended
+				g.Revision++
+				changed = true
+			}
+		}
+		if changed {
+			if s.Revision == math.MaxUint64 {
+				return false, ErrLimit
+			}
+			s.Revision++
+		}
+		// Also initializes a missing authority snapshot; rewrites no active state.
+		return true, ""
+	})
+	if c != "" {
+		return nil, safeGrantCode(c)
+	}
+	if native != nil && native.managed != nil {
+		if c := native.managed.bind(a); c != "" {
+			return nil, c
+		}
+	}
+	if native != nil && native.relaxed != nil {
+		if c := native.relaxed.bind(a); c != "" {
+			return nil, c
+		}
+	}
+	return a, ""
+}
+func validGrantPolicy(p GrantPolicy) bool {
+	return p.Inventory.Valid() && p.Inventory.Protocol == DataProtocol && allReferences(p.Epoch, p.ApprovalBinding, p.CapabilityDigest)
+}
+func safeGrantCode(c Code) Code {
+	if c != "" && !c.Valid() {
+		return ErrUnavailable
+	}
+	return c
+}
+
+// Fence is sticky in memory and must precede the lifecycle owner's durable
+// fence. New owner/epoch always starts with reconciliation, never clears this.
+func (a *GrantAuthority) Fence() {
+	a.mu.Lock()
+	defer a.mu.Unlock()
+	a.fenced = true
+	clear(a.intents)
+}
+
+// transaction is called with the admission mutex held. A policy mismatch also
+// fences the whole authority; it cannot adopt a new epoch on the fly.
+func (a *GrantAuthority) transaction(fn func(*GrantStore) (bool, Code)) Code {
+	if a.gate != nil && !a.gate.allowLocked(a.now()) {
+		// A reload suspension refuses this call without revoking the authority.
+		if a.gate.blocked != "" {
+			a.fenced = true
+			clear(a.intents)
+		}
+		return ErrFenced
+	}
+	if a.fenced {
+		return ErrFenced
+	}
+	c := safeGrantCode(a.repository.Transact(func(p GrantPolicy, s *GrantStore) (bool, Code) {
+		if p != a.policy || !p.Enabled {
+			a.fenced = true
+			clear(a.intents)
+			return false, ErrFenced
+		}
+		return fn(s)
+	}))
+	if c == ErrCommitUncertain || c == ErrUnavailable || c == ErrInternal || c == ErrInvalid || c == ErrIncompatible {
+		a.fenced = true
+		clear(a.intents)
+	}
+	return c
+}
+func (a *GrantAuthority) actor(ctx context.Context, c SessionCarriers, old *NativeActor) (NativeActor, Code) {
+	if a.native == nil {
+		return NativeActor{}, ErrUnavailable
+	}
+	if old != nil {
+		return a.native.Revalidate(ctx, c, *old)
+	}
+	return a.native.Resolve(ctx, c)
+}
+func (a *GrantAuthority) selectConsent(ctx context.Context, actor NativeActor, candidate string, kind ScopeKind, actions []Action) (ConsentSelection, Code) {
+	if a.consent == nil {
+		return ConsentSelection{}, ErrUnavailable
+	}
+	selection, c := a.consent.ValidateConsent(ctx, actor, candidate, kind, slices.Clone(actions))
+	if c = nativeObservationCode(ctx, c); c != "" {
+		return ConsentSelection{}, c
+	}
+	if selection.Principal != actor.Principal() || selection.SessionRef != actor.SessionRef() || selection.Scope.Kind != kind {
+		return ConsentSelection{}, ErrDenied
+	}
+	if !nativeFresh(selection.CheckedAt, a.now()) {
+		return ConsentSelection{}, ErrStale
+	}
+	if !validContinuity(selection.Binding) {
+		return ConsentSelection{}, ErrSuspended
+	}
+	if selection.Binding.Epoch != a.policy.Epoch {
+		return ConsentSelection{}, ErrStale
+	}
+	// Reuse the strict authority shape validator for scope and action validation.
+	probe := Grant{Schema: GrantSchema, ID: candidate, Revision: 1, Inventory: a.policy.Inventory, ApprovalBinding: a.policy.ApprovalBinding, CapabilityDigest: a.policy.CapabilityDigest, Owner: actor.Principal(), Issuer: actor.Principal(), Scope: selection.Scope, Actions: actions, State: GrantActive, CreatedAt: a.now().UnixMilli(), LastValidated: selection.Binding}
+	if c := validateGrant(probe); c != "" {
+		return ConsentSelection{}, c
+	}
+	selection.Scope.Segments = slices.Clone(selection.Scope.Segments)
+	return selection, ""
+}
+func (a *GrantAuthority) Prepare(ctx context.Context, carriers SessionCarriers, candidate string, kind ScopeKind, actions []Action) (Intent, Code) {
+	if !allReferences(candidate) {
+		return Intent{}, ErrInvalid
+	}
+	if kind != ScopePersonal && kind != ScopeShared {
+		return Intent{}, ErrUnsupported
+	}
+	if c := validateGrantActions(actions); c != "" {
+		return Intent{}, c
+	}
+	for _, act := range actions {
+		if !act.ReadOnly() && !a.writes.allows(act) {
+			return Intent{}, ErrUnsupported
+		}
+	}
+	ctx, cancel := context.WithTimeout(ctx, MetadataTimeout)
+	defer cancel()
+	actor, c := a.actor(ctx, carriers, nil)
+	if c != "" {
+		return Intent{}, c
+	}
+	if kind == ScopeShared && !actor.Admin() {
+		return Intent{}, ErrDenied
+	}
+	selection, c := a.selectConsent(ctx, actor, candidate, kind, actions)
+	if c != "" {
+		return Intent{}, c
+	}
+	actor, c = a.actor(ctx, carriers, &actor)
+	if c != "" {
+		return Intent{}, c
+	}
+	a.mu.Lock()
+	defer a.mu.Unlock()
+	var intent Intent
+	c = a.transaction(func(_ *GrantStore) (bool, Code) {
+		now := a.now()
+		if c := nativeContextCode(ctx); c != "" {
+			return false, c
+		}
+		if !nativeFresh(actor.account.CheckedAt, now) || !nativeFresh(selection.CheckedAt, now) {
+			return false, ErrStale
+		}
+		count := 0
+		for id, p := range a.intents {
+			if now.UnixMilli() >= p.intent.ExpiresAt {
+				delete(a.intents, id)
+			} else if p.intent.SubjectRef == actor.Principal().SubjectRef {
+				count++
+			}
+		}
+		if count >= MaxLiveIntents || len(a.intents) >= MaxReplayEntries {
+			return false, ErrBusy
+		}
+		id, c := randomGrantID()
+		if c != "" {
+			return false, c
+		}
+		if _, exists := a.intents[id]; exists {
+			return false, ErrInternal
+		}
+		intent = Intent{ID: id, Inventory: a.policy.Inventory, Epoch: a.policy.Epoch, SubjectRef: actor.Principal().SubjectRef, SessionRef: actor.SessionRef(), CandidateID: candidate, ScopeKind: kind, Actions: slices.Clone(actions), SummaryDigest: consentDigest(a.policy, selection, actions), ExpiresAt: now.Add(IntentTTL).UnixMilli()}
+		a.intents[id] = pendingConsent{intent: intent, actor: actor, selection: selection}
+		return false, ""
+	})
+	if c != "" {
+		return Intent{}, c
+	}
+	intent.Actions = slices.Clone(intent.Actions)
+	return intent, ""
+}
+
+// digest covers the exact scope/actor/session/action/approval/continuity summary;
+// an observation timestamp refresh is not a scope change.
+func consentDigest(policy GrantPolicy, s ConsentSelection, actions []Action) string {
+	s.CheckedAt = time.Time{}
+	b, _ := json.Marshal(struct {
+		Policy    GrantPolicy
+		Selection ConsentSelection
+		Actions   []Action
+	}{policy, s, actions})
+	sum := sha256.Sum256(b)
+	return hex.EncodeToString(sum[:])
+}
+func randomGrantID() (string, Code) {
+	var b [32]byte
+	if _, err := rand.Read(b[:]); err != nil {
+		return "", ErrUnavailable
+	}
+	return hex.EncodeToString(b[:]), ""
+}
+
+func (a *GrantAuthority) Confirm(ctx context.Context, carriers SessionCarriers, id, summary string, storeRevision uint64) (Grant, Code) {
+	if !allReferences(id, summary) || storeRevision == 0 {
+		return Grant{}, ErrInvalid
+	}
+	a.mu.Lock()
+	pending, ok := a.intents[id]
+	fenced := a.fenced
+	if ok && a.now().UnixMilli() >= pending.intent.ExpiresAt {
+		delete(a.intents, id)
+		a.mu.Unlock()
+		return Grant{}, ErrExpired
+	}
+	a.mu.Unlock()
+	if fenced {
+		return Grant{}, ErrFenced
+	}
+	if !ok {
+		return Grant{}, ErrReplay
+	}
+	if summary != pending.intent.SummaryDigest {
+		return Grant{}, ErrDenied
+	}
+	ctx, cancel := context.WithTimeout(ctx, MetadataTimeout)
+	defer cancel()
+	actor, c := a.actor(ctx, carriers, &pending.actor)
+	if c != "" {
+		return Grant{}, c
+	}
+	if pending.intent.ScopeKind == ScopeShared && !actor.Admin() {
+		return Grant{}, ErrDenied
+	}
+	selection, c := a.selectConsent(ctx, actor, pending.intent.CandidateID, pending.intent.ScopeKind, pending.intent.Actions)
+	if c != "" {
+		return Grant{}, c
+	}
+	actor, c = a.actor(ctx, carriers, &actor)
+	if c != "" {
+		return Grant{}, c
+	}
+	if consentDigest(a.policy, selection, pending.intent.Actions) != summary {
+		return Grant{}, ErrStale
+	}
+	a.mu.Lock()
+	defer a.mu.Unlock()
+	var grant Grant
+	c = a.transaction(func(s *GrantStore) (bool, Code) {
+		current, exists := a.intents[id]
+		if !exists {
+			return false, ErrReplay
+		}
+		now := a.now()
+		if c := nativeContextCode(ctx); c != "" {
+			return false, c
+		}
+		if now.UnixMilli() >= current.intent.ExpiresAt {
+			delete(a.intents, id)
+			return false, ErrExpired
+		}
+		if !nativeFresh(actor.account.CheckedAt, now) || !nativeFresh(selection.CheckedAt, now) {
+			return false, ErrStale
+		}
+		if s.Revision != storeRevision {
+			return false, ErrStale
+		}
+		if len(s.Grants) >= MaxGrants || s.Revision == math.MaxUint64 {
+			return false, ErrLimit
+		}
+		newID, c := randomGrantID()
+		if c != "" {
+			return false, c
+		}
+		if findGrant(s, newID) != nil {
+			return false, ErrInternal
+		}
+		grant = Grant{Schema: GrantSchema, ID: newID, Revision: 1, Inventory: a.policy.Inventory, ApprovalBinding: a.policy.ApprovalBinding, CapabilityDigest: a.policy.CapabilityDigest, Owner: actor.Principal(), Issuer: actor.Principal(), Scope: selection.Scope, Actions: slices.Clone(pending.intent.Actions), State: GrantActive, CreatedAt: now.UnixMilli(), LastValidated: selection.Binding}
+		// Burn before committing. Failure/uncertainty never allows intent replay.
+		delete(a.intents, id)
+		s.Grants = append(s.Grants, cloneAuthorityGrant(grant))
+		s.Revision++
+		return true, ""
+	})
+	if c != "" {
+		return Grant{}, c
+	}
+	return grant, ""
+}
+
+// WithGrantAdmission reserves an S2 slot while holding the shared ordering
+// point and the short disk locks. reserve MUST be nonblocking and must not call
+// back into authority. It executes no file operations in S3.
+func (a *GrantAuthority) WithGrantAdmission(proof GrantAdmission, reserve func(Grant, NativeActor) Code) Code {
+	if !proof.Actor.valid || !nativeFresh(proof.Actor.account.CheckedAt, a.now()) {
+		return ErrDenied
+	}
+	if !allReferences(proof.GrantID) || proof.Revision == 0 || reserve == nil {
+		return ErrInvalid
+	}
+	if !proof.Action.ReadOnly() && !a.writes.allows(proof.Action) {
+		return ErrUnsupported
+	}
+	a.mu.Lock()
+	defer a.mu.Unlock()
+	if c := a.relaxedActorLocked(proof.Actor); c != "" {
+		return c
+	}
+	if proof.Actor.managed != nil {
+		m := proof.Actor.managed
+		if a.native == nil || a.native.managed != m || m.authority != a || !m.record.Enabled || proof.Actor.Principal().InstanceRef != m.record.Generation || proof.Actor.SessionRef() != m.record.SessionRef {
+			return ErrFenced
+		}
+	} else if a.native != nil && a.native.managed != nil {
+		return ErrDenied
+	}
+	suspended := false
+	suspensionAttempted := false
+	code := a.transaction(func(s *GrantStore) (bool, Code) {
+		if !nativeFresh(proof.Actor.account.CheckedAt, a.now()) {
+			return false, ErrStale
+		}
+		g := findGrant(s, proof.GrantID)
+		if g == nil {
+			return false, ErrDenied
+		}
+		if g.Scope.Kind == ScopePersonal && g.Owner != proof.Actor.Principal() {
+			return false, ErrDenied
+		}
+		if g.State == GrantRevoked {
+			return false, ErrRevoked
+		}
+		if g.Revision != proof.Revision {
+			return false, ErrStale
+		}
+		if g.State == GrantSuspended {
+			return false, ErrSuspended
+		}
+		if g.Inventory != a.policy.Inventory || g.ApprovalBinding != a.policy.ApprovalBinding || g.CapabilityDigest != a.policy.CapabilityDigest || g.EffectiveState(proof.Binding, proof.Continuous) != GrantActive {
+			suspensionAttempted = true
+			if g.Revision == math.MaxUint64 || s.Revision == math.MaxUint64 {
+				return false, ErrLimit
+			}
+			g.State = GrantSuspended
+			g.Reason = ErrSuspended
+			g.Revision++
+			s.Revision++
+			suspended = true
+			return true, ""
+		}
+		if !slices.Contains(g.Actions, proof.Action) {
+			return false, ErrDenied
+		}
+		return false, safeGrantCode(reserve(cloneAuthorityGrant(*g), proof.Actor))
+	})
+	if code != "" && suspensionAttempted {
+		a.fenced = true
+		clear(a.intents)
+	}
+	if code == "" && suspended {
+		return ErrSuspended
+	}
+	return code
+}
+
+func (a *GrantAuthority) Revoke(ctx context.Context, carriers SessionCarriers, id string, revision, storeRevision uint64) (RevokeResult, Code) {
+	if !allReferences(id) || revision == 0 || storeRevision == 0 {
+		return RevokeResult{}, ErrInvalid
+	}
+	actor, c := a.actor(ctx, carriers, nil)
+	if c != "" {
+		return RevokeResult{}, c
+	}
+	a.mu.Lock()
+	result := RevokeResult{}
+	key := GrantDrainKey{}
+	c = a.transaction(func(s *GrantStore) (bool, Code) {
+		if c := nativeContextCode(ctx); c != "" {
+			return false, c
+		}
+		if !nativeFresh(actor.account.CheckedAt, a.now()) {
+			return false, ErrStale
+		}
+		g := findGrant(s, id)
+		if g == nil {
+			return false, ErrDenied
+		}
+		if !actor.Admin() && (g.Scope.Kind != ScopePersonal || g.Owner != actor.Principal()) {
+			return false, ErrDenied
+		}
+		if s.Revision != storeRevision || g.Revision != revision {
+			return false, ErrStale
+		}
+		if g.State != GrantRevoked {
+			if g.Revision == math.MaxUint64 || s.Revision == math.MaxUint64 {
+				return false, ErrLimit
+			}
+			// Admission mutex provides memory deny through persistence. On any failure
+			// the whole owner is fenced; no new work sneaks through a failed R.
+			g.State = GrantRevoked
+			g.Reason = ErrRevoked
+			g.RevokedAt = max(g.CreatedAt, a.now().UnixMilli())
+			g.Revision++
+			s.Revision++
+			result = RevokeResult{GrantID: id, Revision: g.Revision}
+			key = GrantDrainKey{a.policy.Epoch, id, g.Revision}
+			return true, ""
+		}
+		result = RevokeResult{GrantID: id, Revision: g.Revision}
+		key = GrantDrainKey{a.policy.Epoch, id, g.Revision}
+		return false, ""
+	})
+	if c != "" && key.GrantID != "" {
+		a.fenced = true
+		clear(a.intents)
+	}
+	a.mu.Unlock()
+	// Best-effort stop after an uncertain/failed R; never claim durable R or Q.
+	if c != "" {
+		if key.GrantID != "" {
+			_, _ = a.drain(ctx, key)
+		}
+		return result, c
+	}
+	result.Revoked = true
+	proof, c := a.drain(ctx, key)
+	if c != "" {
+		return result, ErrCleanupRequired
+	}
+	a.mu.Lock()
+	defer a.mu.Unlock()
+	// Q is a separate durable artifact, not part of grants.json schema 1. Saving
+	// cannot resurrect authority and is allowed after a concurrent global fence.
+	c = safeGrantCode(a.repository.SaveQuiescence(proof))
+	if c != "" {
+		if c != ErrBusy {
+			a.fenced = true
+		}
+		return result, ErrCleanupRequired
+	}
+	result.Drained = true
+	return result, ""
+}
+func (a *GrantAuthority) drain(ctx context.Context, key GrantDrainKey) (GrantQuiescence, Code) {
+	if a.cohort == nil {
+		return GrantQuiescence{}, ErrCleanupRequired
+	}
+	ctx, cancel := context.WithTimeout(ctx, RevokeDrainTimeout)
+	defer cancel()
+	q, c := a.cohort.DrainGrant(ctx, key)
+	if c = nativeObservationCode(ctx, c); c != "" || q.Key != key || !completeQuiescence(q) {
+		return GrantQuiescence{}, ErrCleanupRequired
+	}
+	return q, ""
+}

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

@@ -0,0 +1,88 @@
+package helper
+
+import (
+	"context"
+	"time"
+)
+
+// S3 is root-supervisor-owned. Only exact-owned-helper private RPC is wired;
+// public helper sockets/CGI/generators expose no grant or data capability.
+// Exactly one supervisor owns an authority for one epoch. Its admission order
+// must also own S2 reservations and lifecycle fencing, not a helper-local mutex.
+
+// GrantPolicy is derived under policy.lock from the current schema 2 approval.
+// ApprovalBinding hashes the complete approval (including boot/install binding);
+// CapabilityDigest pins the approved read-only registry ceiling.
+type GrantPolicy struct {
+	Inventory        Inventory
+	Epoch            string
+	ApprovalBinding  string
+	CapabilityDigest string
+	Enabled          bool
+}
+
+// GrantRepository runs only bounded local storage work. Lock order is the
+// authority admission mutex -> policy.lock -> grants.lock. It decodes BOTH
+// snapshots on every transaction. true requests a durable grant-only commit;
+// two snapshots are never represented as one atomic transaction. Missing grants
+// means an empty revision-1 store; malformed existing authority fails closed.
+// A failed/uncertain commit must poison the repository until restart/reconcile.
+type GrantRepository interface {
+	Transact(func(GrantPolicy, *GrantStore) (bool, Code)) Code
+	// SaveQuiescence durably records a complete proof only for a matching
+	// revoked ID/revision. It never changes or enables grant authority.
+	SaveQuiescence(GrantQuiescence) Code
+}
+
+// ConsentValidator is a trusted S1/S5 candidate/ACL/object adapter, not browser
+// input. It rechecks current local mount, own-home/shared scope and action ACL.
+// No implementation may persist carriers or touch NAS in S3 tests.
+type ConsentValidator interface {
+	ValidateConsent(context.Context, NativeActor, string, ScopeKind, []Action) (ConsentSelection, Code)
+}
+
+type ConsentSelection struct {
+	Principal  Principal
+	SessionRef string
+	Scope      Scope
+	Binding    ContinuityBinding
+	CheckedAt  time.Time
+}
+
+// GrantCohort is the S2 seam. Drain runs OUTSIDE admission and disk locks, with
+// a <=2s observation deadline. It must close relay gates, cancel/reap all owned
+// children, close leases/FDs and account for already admitted effects. Context
+// cancellation, a signal, helper exit or transport EOF is never this proof.
+type GrantCohort interface {
+	DrainGrant(context.Context, GrantDrainKey) (GrantQuiescence, Code)
+}
+
+type GrantDrainKey struct {
+	Epoch    string
+	GrantID  string
+	Revision uint64 // revoked revision; includes all earlier admissions for the ID
+}
+
+type GrantQuiescence struct {
+	Cohort          *GrantDrainProof `json:"cohort,omitempty"`
+	Key             GrantDrainKey
+	ChildrenReaped  bool
+	RelayClosed     bool
+	LeasesClosed    bool
+	FDsClosed       bool
+	EffectsRecorded bool
+}
+
+// GrantAdmission is a trusted in-memory use proof. S2/S5 must freshly establish
+// App permission, actor identity/ACL and subject/scope continuity before this
+// call; it is NOT a wire shape, a bearer capability or an ACL substitute.
+// Reservation is nonblocking, never executes I/O, and registers the operation
+// with the same supervisor cohort BEFORE releasing the admission order.
+type GrantAdmission struct {
+	Actor      NativeActor
+	GrantID    string
+	Revision   uint64
+	Action     Action
+	Binding    ContinuityBinding
+	Continuous bool
+}