@opensoha/contracts 0.1.23 → 0.1.25

package/agent/guest/protocol.go

@@ -0,0 +1,235 @@
+// Package guest carries the personal VM guest registration and heartbeat protocol.
+// Schemas in agent/ own the wire shapes. This protocol grants no task execution.
+package guest
+
+import (
+	"bytes"
+	"crypto/sha256"
+	"encoding/base64"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"regexp"
+	"slices"
+	"strings"
+	"time"
+	"unicode/utf8"
+)
+
+const (
+	BindingVersion    = "opensoha.dev/personal-guest-binding/v1"
+	EnrollmentVersion = "opensoha.dev/personal-guest-enrollment/v1"
+	HeartbeatVersion  = "opensoha.dev/personal-guest-heartbeat/v1"
+	MaxClockSkew      = 30 * time.Second
+	MaxCounter        = 1<<53 - 1 // Exact integer range shared by Go and JavaScript consumers.
+	EnrollmentMinTTL  = time.Minute
+	EnrollmentMaxTTL  = 10 * time.Minute
+	BindingsPath      = "/api/personal-guest/v1/bindings"
+)
+
+var (
+	uuidPattern   = regexp.MustCompile(`^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$`)
+	digestPattern = regexp.MustCompile(`^sha256:[a-f0-9]{64}$`)
+	serialPattern = regexp.MustCompile(`^[A-Za-z0-9_-]{1,20}$`)
+)
+
+// Binding is derived by Core and immutable for this guest registration. Version
+// is the identity revision, independent of environment operation CAS versions.
+type Binding struct {
+	SchemaVersion        string    `json:"schemaVersion"`
+	ID                   string    `json:"id"`
+	Version              int64     `json:"version"`
+	AssistantID          string    `json:"assistantId"`
+	OwnerID              string    `json:"ownerId"`
+	Provider             string    `json:"provider"`
+	ComputeRef           string    `json:"computeRef"`
+	ComputeGeneration    int64     `json:"computeGeneration"`
+	ProviderIdentityHash string    `json:"providerIdentityHash"`
+	DataRef              string    `json:"dataRef"`
+	DataDiskSerial       string    `json:"dataDiskSerial"`
+	DataDiskBytes        int64     `json:"dataDiskBytes"`
+	PolicyRevision       string    `json:"policyRevision"`
+	IssuedAt             time.Time `json:"issuedAt"`
+	ExpiresAt            time.Time `json:"expiresAt"`
+}
+
+// Enrollment is sent over mutually authenticated TLS using a short, one-time
+// challenge in the Authorization header. The certificate pins guest identity.
+// No owner, capability, filesystem path or provider credentials are client input.
+type Enrollment struct {
+	SchemaVersion string `json:"schemaVersion"`
+	EnrollmentID  string `json:"enrollmentId"`
+}
+
+// EnrollmentTokenHash accepts exactly Bearer plus a canonical unpadded base64url
+// 32-byte challenge. Core generates it with crypto/rand and stores only the hash.
+// Its 60–600 second grant pins the binding and guest certificate fingerprint;
+// atomic consumption, expiry and current authorization remain service duties.
+func EnrollmentTokenHash(authorization string) (string, error) {
+	token, ok := strings.CutPrefix(authorization, "Bearer ")
+	if !ok || len(token) != 43 {
+		return "", errors.New("invalid personal guest enrollment authorization")
+	}
+	random, err := base64.RawURLEncoding.Strict().DecodeString(token)
+	if err != nil || len(random) != 32 {
+		return "", errors.New("invalid personal guest enrollment authorization")
+	}
+	digest := sha256.Sum256([]byte(token))
+	return fmt.Sprintf("sha256:%x", digest), nil
+}
+
+// Heartbeat proves only current authenticated liveness. Core independently
+// checks current authorization, frozen binding and monotonic sequence in storage.
+// A guest cannot claim data/tool/browser readiness with this message.
+type Heartbeat struct {
+	SchemaVersion     string    `json:"schemaVersion"`
+	BindingID         string    `json:"bindingId"`
+	BindingVersion    int64     `json:"bindingVersion"`
+	ComputeGeneration int64     `json:"computeGeneration"`
+	Sequence          int64     `json:"sequence"`
+	ObservedAt        time.Time `json:"observedAt"`
+}
+
+func (b Binding) Validate() error {
+	if b.SchemaVersion != BindingVersion || b.Version < 1 || b.Version > MaxCounter || b.ComputeGeneration < 1 || b.ComputeGeneration > MaxCounter || b.Provider != "pve" && b.Provider != "kubevirt" {
+		return errors.New("invalid personal guest binding version or provider")
+	}
+	for _, id := range []string{b.ID, b.AssistantID, b.OwnerID, b.ComputeRef, b.DataRef} {
+		if !uuidPattern.MatchString(id) {
+			return errors.New("invalid personal guest binding identity")
+		}
+	}
+	if !serialPattern.MatchString(b.DataDiskSerial) || b.DataDiskBytes < 16<<20 || b.DataDiskBytes > 1<<40 || !digestPattern.MatchString(b.PolicyRevision) || !digestPattern.MatchString(b.ProviderIdentityHash) {
+		return errors.New("invalid personal guest data identity or policy revision")
+	}
+	if b.IssuedAt.IsZero() || !b.ExpiresAt.After(b.IssuedAt) || b.ExpiresAt.Sub(b.IssuedAt) > 24*time.Hour {
+		return errors.New("invalid personal guest binding lifetime")
+	}
+	return nil
+}
+
+func (e Enrollment) Validate() error {
+	if e.SchemaVersion != EnrollmentVersion || !uuidPattern.MatchString(e.EnrollmentID) {
+		return errors.New("invalid personal guest enrollment")
+	}
+	return nil
+}
+
+func (h Heartbeat) Validate() error {
+	if h.SchemaVersion != HeartbeatVersion || !uuidPattern.MatchString(h.BindingID) || h.BindingVersion < 1 || h.BindingVersion > MaxCounter || h.ComputeGeneration < 1 || h.ComputeGeneration > MaxCounter || h.Sequence < 1 || h.Sequence > MaxCounter || h.ObservedAt.IsZero() {
+		return errors.New("invalid personal guest heartbeat")
+	}
+	return nil
+}
+
+// ValidateFor is not authentication or a readiness grant. Callers must first
+// authenticate the pinned guest certificate and recheck authoritative ownership.
+func (h Heartbeat) ValidateFor(binding Binding, now time.Time, lastSequence int64) error {
+	if err := binding.Validate(); err != nil {
+		return err
+	}
+	if err := h.Validate(); err != nil {
+		return err
+	}
+	if now.IsZero() || now.Before(binding.IssuedAt) || !now.Before(binding.ExpiresAt) || lastSequence < 0 {
+		return errors.New("personal guest binding is not currently valid")
+	}
+	if h.BindingID != binding.ID || h.BindingVersion != binding.Version || h.ComputeGeneration != binding.ComputeGeneration || h.Sequence <= lastSequence {
+		return errors.New("personal guest heartbeat binding or sequence mismatch")
+	}
+	if h.ObservedAt.Before(binding.IssuedAt) || !h.ObservedAt.Before(binding.ExpiresAt) || h.ObservedAt.Before(now.Add(-MaxClockSkew)) || h.ObservedAt.After(now.Add(MaxClockSkew)) {
+		return errors.New("personal guest heartbeat observation is stale")
+	}
+	return nil
+}
+
+func decodeStrict(data []byte, value any, keys ...string) error {
+	return decodeStrictBounded(data, value, 4096, keys...)
+}
+
+func decodeStrictBounded(data []byte, value any, limit int, keys ...string) error {
+	if len(data) > limit || !utf8.Valid(data) {
+		return errors.New("personal guest message must be bounded UTF-8")
+	}
+	if err := validateObjectKeys(data, keys); err != nil {
+		return err
+	}
+	decoder := json.NewDecoder(bytes.NewReader(data))
+	decoder.DisallowUnknownFields()
+	if err := decoder.Decode(value); err != nil {
+		return err
+	}
+	if decoder.Decode(new(any)) != io.EOF {
+		return errors.New("personal guest message must contain one JSON object")
+	}
+	return nil
+}
+
+func validateObjectKeys(data []byte, keys []string) error {
+	decoder := json.NewDecoder(bytes.NewReader(data))
+	start, err := decoder.Token()
+	if err != nil || start != json.Delim('{') {
+		return errors.New("personal guest message must be a JSON object")
+	}
+	seen := make(map[string]bool, len(keys))
+	for decoder.More() {
+		key, err := decoder.Token()
+		if err != nil {
+			return err
+		}
+		name, ok := key.(string)
+		if !ok || seen[name] || !slices.Contains(keys, name) {
+			return errors.New("personal guest message contains a duplicate or unknown field")
+		}
+		seen[name] = true
+		var value json.RawMessage
+		if err := decoder.Decode(&value); err != nil {
+			return err
+		}
+	}
+	_, err = decoder.Token()
+	return err
+}
+
+func (b *Binding) UnmarshalJSON(data []byte) error {
+	type wire Binding
+	var value wire
+	if err := decodeStrict(data, &value, "schemaVersion", "id", "version", "assistantId", "ownerId", "provider", "computeRef", "computeGeneration", "providerIdentityHash", "dataRef", "dataDiskSerial", "dataDiskBytes", "policyRevision", "issuedAt", "expiresAt"); err != nil {
+		return err
+	}
+	decoded := Binding(value)
+	if err := decoded.Validate(); err != nil {
+		return err
+	}
+	*b = decoded
+	return nil
+}
+
+func (e *Enrollment) UnmarshalJSON(data []byte) error {
+	type wire Enrollment
+	var value wire
+	if err := decodeStrict(data, &value, "schemaVersion", "enrollmentId"); err != nil {
+		return err
+	}
+	decoded := Enrollment(value)
+	if err := decoded.Validate(); err != nil {
+		return err
+	}
+	*e = decoded
+	return nil
+}
+
+func (h *Heartbeat) UnmarshalJSON(data []byte) error {
+	type wire Heartbeat
+	var value wire
+	if err := decodeStrict(data, &value, "schemaVersion", "bindingId", "bindingVersion", "computeGeneration", "sequence", "observedAt"); err != nil {
+		return err
+	}
+	decoded := Heartbeat(value)
+	if err := decoded.Validate(); err != nil {
+		return err
+	}
+	*h = decoded
+	return nil
+}

package/agent/guest/protocol_test.go

@@ -0,0 +1,142 @@
+package guest
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+)
+
+func TestEnrollmentAuthorizationUsesCanonicalBoundedChallenge(t *testing.T) {
+	valid := "Bearer " + strings.Repeat("A", 43)
+	digest, err := EnrollmentTokenHash(valid)
+	if err != nil || !digestPattern.MatchString(digest) {
+		t.Fatalf("challenge hash: %q %v", digest, err)
+	}
+	for _, invalid := range []string{"", "Basic " + strings.Repeat("A", 43), valid + "=", valid + " ", " " + valid, "Bearer " + strings.Repeat("A", 42) + "B"} {
+		if _, err := EnrollmentTokenHash(invalid); err == nil {
+			t.Fatal("noncanonical enrollment challenge accepted")
+		}
+	}
+}
+
+func TestSchemaFixtures(t *testing.T) {
+	for name, decode := range map[string]func([]byte) error{
+		"binding":    func(data []byte) error { return json.Unmarshal(data, new(Binding)) },
+		"enrollment": func(data []byte) error { return json.Unmarshal(data, new(Enrollment)) },
+		"heartbeat":  func(data []byte) error { return json.Unmarshal(data, new(Heartbeat)) },
+	} {
+		for _, kind := range []string{"valid", "invalid"} {
+			files, err := filepath.Glob(filepath.Join("../../fixtures/json-schema/personal-guest-"+name, kind, "*.json"))
+			if err != nil || len(files) == 0 {
+				t.Fatalf("missing %s/%s fixtures: %v", name, kind, err)
+			}
+			for _, file := range files {
+				t.Run(name+"/"+kind+"/"+filepath.Base(file), func(t *testing.T) {
+					data, err := os.ReadFile(file)
+					if err != nil {
+						t.Fatal(err)
+					}
+					if err := decode(data); (err == nil) != (kind == "valid") {
+						t.Fatalf("fixture result: %v", err)
+					}
+				})
+			}
+		}
+	}
+}
+
+func guestFixture[T any](t *testing.T, name string) T {
+	t.Helper()
+	data, err := os.ReadFile("../../fixtures/json-schema/personal-guest-" + name + "/valid/minimal.json")
+	if err != nil {
+		t.Fatal(err)
+	}
+	var value T
+	if err := json.Unmarshal(data, &value); err != nil {
+		t.Fatal(err)
+	}
+	return value
+}
+
+func TestHeartbeatRequiresCurrentBindingAndFreshMonotonicObservation(t *testing.T) {
+	binding := guestFixture[Binding](t, "binding")
+	heartbeat := guestFixture[Heartbeat](t, "heartbeat")
+	now := heartbeat.ObservedAt
+	if err := heartbeat.ValidateFor(binding, now, 0); err != nil {
+		t.Fatal(err)
+	}
+	for name, mutate := range map[string]func(*Heartbeat){
+		"different binding": func(h *Heartbeat) { h.BindingID = binding.DataRef },
+		"old revision":      func(h *Heartbeat) { h.BindingVersion++ },
+		"old compute":       func(h *Heartbeat) { h.ComputeGeneration++ },
+		"zero sequence":     func(h *Heartbeat) { h.Sequence = 0 },
+		"inexact sequence":  func(h *Heartbeat) { h.Sequence = MaxCounter + 1 },
+		"future clock":      func(h *Heartbeat) { h.ObservedAt = now.Add(MaxClockSkew + time.Nanosecond) },
+		"old clock":         func(h *Heartbeat) { h.ObservedAt = now.Add(-MaxClockSkew - time.Nanosecond) },
+		"expired observation": func(h *Heartbeat) {
+			h.ObservedAt = binding.ExpiresAt
+		},
+	} {
+		t.Run(name, func(t *testing.T) {
+			h := heartbeat
+			mutate(&h)
+			if h.ValidateFor(binding, now, 0) == nil {
+				t.Fatal("invalid heartbeat accepted")
+			}
+		})
+	}
+	for name, serverNow := range map[string]time.Time{
+		"zero clock": {}, "not yet valid": binding.IssuedAt.Add(-time.Nanosecond), "expired": binding.ExpiresAt,
+	} {
+		t.Run(name, func(t *testing.T) {
+			if heartbeat.ValidateFor(binding, serverNow, 0) == nil {
+				t.Fatal("invalid binding deadline accepted")
+			}
+		})
+	}
+	if heartbeat.ValidateFor(binding, now, heartbeat.Sequence) == nil || heartbeat.ValidateFor(binding, now, -1) == nil {
+		t.Fatal("replay or invalid server sequence accepted")
+	}
+	heartbeat.Sequence++
+	if err := heartbeat.ValidateFor(binding, now, heartbeat.Sequence-1); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestBindingRejectsInvalidLifetime(t *testing.T) {
+	binding := guestFixture[Binding](t, "binding")
+	for _, expiresAt := range []time.Time{binding.IssuedAt, binding.IssuedAt.Add(-time.Second), binding.IssuedAt.Add(24*time.Hour + time.Nanosecond)} {
+		binding.ExpiresAt = expiresAt
+		if binding.Validate() == nil {
+			t.Fatal("invalid credential lifetime accepted")
+		}
+	}
+}
+
+func TestDecodeRejectsUnknownFieldsInvalidUTF8AndOversizedMessages(t *testing.T) {
+	valid, err := json.Marshal(guestFixture[Heartbeat](t, "heartbeat"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	for name, data := range map[string][]byte{
+		"invalid UTF8": append(append([]byte{}, valid[:len(valid)-1]...), 0xff, '}'),
+		"null":         []byte("null"),
+		"oversized":    append(valid, make([]byte, 4096)...),
+		"legacy owner": append(append([]byte{}, valid[:len(valid)-1]...), []byte(",\"ownerId\":\"other\"}")...),
+		"duplicate":    append(append([]byte{}, valid[:len(valid)-1]...), []byte(",\"sequence\":2}")...),
+		"wrong case":   []byte(strings.Replace(string(valid), "\"sequence\"", "\"Sequence\"", 1)),
+	} {
+		t.Run(name, func(t *testing.T) {
+			if json.Unmarshal(data, new(Heartbeat)) == nil {
+				t.Fatal("invalid wire message accepted")
+			}
+		})
+	}
+	type wireHeartbeat Heartbeat
+	if decodeStrict(append(valid, []byte(" {}")...), new(wireHeartbeat), "schemaVersion", "bindingId", "bindingVersion", "computeGeneration", "sequence", "observedAt") == nil {
+		t.Fatal("trailing object accepted")
+	}
+}

package/agent/guest/renewal.go

@@ -0,0 +1,56 @@
+package guest
+
+import (
+	"errors"
+	"time"
+)
+
+const RenewalVersion = "opensoha.dev/personal-guest-renewal/v1"
+
+// Renewal is authenticated with the current certificate. Core derives every
+// identity field; requestId makes a lost issuance response recoverable.
+type Renewal struct {
+	SchemaVersion  string `json:"schemaVersion"`
+	RequestID      string `json:"requestId"`
+	BindingVersion int64  `json:"bindingVersion"`
+	CSRPEM         string `json:"csrPEM"`
+}
+
+type RenewalResult struct {
+	RequestID      string    `json:"requestId"`
+	Binding        Binding   `json:"binding"`
+	CertificatePEM string    `json:"certificatePEM"`
+	ClientCAPEM    string    `json:"clientCAPEM"`
+	CommitBefore   time.Time `json:"commitBefore"`
+}
+
+func (r Renewal) Validate() error {
+	if r.SchemaVersion != RenewalVersion || !uuidPattern.MatchString(r.RequestID) || r.BindingVersion < 1 || r.BindingVersion >= MaxCounter || len(r.CSRPEM) == 0 || len(r.CSRPEM) > 2048 {
+		return errors.New("invalid personal guest renewal")
+	}
+	return nil
+}
+
+func (r *Renewal) UnmarshalJSON(data []byte) error {
+	type wire Renewal
+	var value wire
+	if err := decodeStrict(data, &value, "schemaVersion", "requestId", "bindingVersion", "csrPEM"); err != nil {
+		return err
+	}
+	decoded := Renewal(value)
+	if err := decoded.Validate(); err != nil {
+		return err
+	}
+	*r = decoded
+	return nil
+}
+
+// SameWorkspace excludes only registration and lease fields. It is not an
+// authorization check and must never authorize a disk format by itself.
+func (b Binding) SameWorkspace(other Binding) bool {
+	b.ID, other.ID = "", ""
+	b.Version, other.Version = 0, 0
+	b.IssuedAt = other.IssuedAt
+	b.ExpiresAt = other.ExpiresAt
+	return b == other
+}

package/agent/guest/renewal_test.go

@@ -0,0 +1,53 @@
+package guest
+
+import (
+	"encoding/json"
+	"testing"
+	"time"
+)
+
+func TestRenewalRejectsDuplicateAndUnknownAuthority(t *testing.T) {
+	for _, raw := range []string{`{"schemaVersion":"opensoha.dev/personal-guest-renewal/v1","requestId":"11111111-1111-4111-8111-111111111111","bindingVersion":1,"bindingVersion":2,"csrPEM":"public"}`, `{"schemaVersion":"opensoha.dev/personal-guest-renewal/v1","requestId":"11111111-1111-4111-8111-111111111111","bindingVersion":1,"csrPEM":"public","ownerId":"other"}`} {
+		var request Renewal
+		if json.Unmarshal([]byte(raw), &request) == nil {
+			t.Fatal("untrusted renewal fields accepted")
+		}
+	}
+}
+
+func TestSameWorkspaceIgnoresOnlyRegistrationAndLeaseFields(t *testing.T) {
+	binding := guestFixture[Binding](t, "binding")
+	renewed := binding
+	renewed.ID = "another-registration"
+	renewed.Version++
+	renewed.IssuedAt = renewed.IssuedAt.Add(time.Hour)
+	renewed.ExpiresAt = renewed.ExpiresAt.Add(time.Hour)
+	beforeBinding, beforeRenewed := binding, renewed
+	if !binding.SameWorkspace(renewed) || !renewed.SameWorkspace(binding) {
+		t.Fatal("registration or lease changes changed workspace identity")
+	}
+	if binding != beforeBinding || renewed != beforeRenewed {
+		t.Fatal("workspace comparison mutated a binding")
+	}
+	for name, mutate := range map[string]func(*Binding){
+		"schema":            func(b *Binding) { b.SchemaVersion += "-other" },
+		"assistant":         func(b *Binding) { b.AssistantID += "-other" },
+		"owner":             func(b *Binding) { b.OwnerID += "-other" },
+		"provider":          func(b *Binding) { b.Provider += "-other" },
+		"compute":           func(b *Binding) { b.ComputeRef += "-other" },
+		"generation":        func(b *Binding) { b.ComputeGeneration++ },
+		"provider identity": func(b *Binding) { b.ProviderIdentityHash += "-other" },
+		"data":              func(b *Binding) { b.DataRef += "-other" },
+		"disk serial":       func(b *Binding) { b.DataDiskSerial += "-other" },
+		"disk size":         func(b *Binding) { b.DataDiskBytes++ },
+		"policy":            func(b *Binding) { b.PolicyRevision += "-other" },
+	} {
+		t.Run(name, func(t *testing.T) {
+			other := renewed
+			mutate(&other)
+			if binding.SameWorkspace(other) || other.SameWorkspace(binding) {
+				t.Fatal("different workspace identity accepted")
+			}
+		})
+	}
+}