@synopackageland/cli 0.4.1 → 0.5.0

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

@@ -0,0 +1,559 @@
+//go:build synopkgland_sdk_workers
+
+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
+	background  *sdkBackgroundPending
+	interactive *sdkInteractivePending
+}
+
+// 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
+	sdkJobs       *sdkJobOwner
+	sdkBackground *sdkBackgroundOwner
+	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 := s.Schema == 1
+		s.Schema = 2
+		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
+			}
+		}
+		for n := range s.Background {
+			r := &s.Background[n]
+			if r.State == "active" || r.State == "consumed" {
+				if r.Binding.Binding.Delegation.Revision == math.MaxUint64 {
+					return false, ErrLimit
+				}
+				r.State = "suspended"
+				r.Reason = "suspended"
+				r.Binding.Binding.Delegation.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)
+	if a.sdkJobs != nil {
+		if a.sdkJobs.session != nil {
+			a.sdkJobs.session.deny()
+		}
+		for _, j := range a.sdkJobs.jobs {
+			a.sdkJobs.reject(j, ErrFenced)
+		}
+	}
+}
+
+// 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
+		}
+		write, c := fn(s)
+		if c == "" && write {
+			if _, c = a.sdkInvalidateDerivedLocked(s, nil); c != "" {
+				return false, c
+			}
+		}
+		return write, c
+	}))
+	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]
+	if ok && (pending.background != nil || pending.interactive != nil) {
+		a.mu.Unlock()
+		return Grant{}, ErrUnsupported
+	}
+	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)+len(s.Background) >= 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
+	}
+	if a.sdkBackground != nil {
+		if c := a.sdkBackground.finishParentLocked(id); c != "" {
+			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, ""
+}