@7h3/protocol 0.4.0 → 0.5.0

package/sdk/go/encryption_test.go

@@ -0,0 +1,318 @@
+package protocol7h3_test
+
+import (
+	"encoding/base64"
+	"encoding/json"
+	"strings"
+	"testing"
+	"time"
+
+	protocol7h3 "github.com/IceMasterT/7h3-protocol/sdk/go"
+)
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+func makeEnvelopeGo(t *testing.T, body protocol7h3.ProtocolBody) protocol7h3.ProtocolEnvelope {
+	t.Helper()
+	nowMs := time.Now().UnixMilli()
+	return protocol7h3.ProtocolEnvelope{
+		Header: protocol7h3.ProtocolHeader{
+			Version:     "7h3/0.1",
+			MessageID:   "msg-go-test",
+			TimestampMs: nowMs,
+			TTLMs:       60_000,
+			Sender:      "agent-alice",
+			Recipient:   "agent-bob",
+			Nonce:       "test-nonce-go",
+		},
+		Body: body,
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Test 1: GenerateX25519KeyPair returns 32-byte base64url keys (~43 chars, no padding)
+// ---------------------------------------------------------------------------
+
+func TestGenerateX25519KeyPair(t *testing.T) {
+	pub, priv, err := protocol7h3.GenerateX25519KeyPair()
+	if err != nil {
+		t.Fatalf("GenerateX25519KeyPair error: %v", err)
+	}
+
+	// Should not contain base64 padding
+	if strings.Contains(pub, "=") {
+		t.Errorf("public key has padding: %s", pub)
+	}
+	if strings.Contains(priv, "=") {
+		t.Errorf("private key has padding: %s", priv)
+	}
+
+	// Should be 43 chars (base64url of 32 bytes without padding)
+	if len(pub) != 43 {
+		t.Errorf("public key length = %d, want 43", len(pub))
+	}
+	if len(priv) != 43 {
+		t.Errorf("private key length = %d, want 43", len(priv))
+	}
+
+	// Decoded must be exactly 32 bytes
+	pubBytes, err := base64.RawURLEncoding.DecodeString(pub)
+	if err != nil {
+		t.Fatalf("decode public key: %v", err)
+	}
+	if len(pubBytes) != 32 {
+		t.Errorf("public key decoded length = %d, want 32", len(pubBytes))
+	}
+
+	privBytes, err := base64.RawURLEncoding.DecodeString(priv)
+	if err != nil {
+		t.Fatalf("decode private key: %v", err)
+	}
+	if len(privBytes) != 32 {
+		t.Errorf("private key decoded length = %d, want 32", len(privBytes))
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Test 2: SealEnvelope + OpenEnvelope round-trip recovers original body exactly
+// ---------------------------------------------------------------------------
+
+func TestSealOpenEnvelopeRoundTrip(t *testing.T) {
+	recipientPub, recipientPriv, err := protocol7h3.GenerateX25519KeyPair()
+	if err != nil {
+		t.Fatalf("GenerateX25519KeyPair: %v", err)
+	}
+
+	senderPub, senderPriv, err := protocol7h3.GenerateKeypair()
+	if err != nil {
+		t.Fatalf("GenerateKeypair: %v", err)
+	}
+
+	originalBody := protocol7h3.ProtocolBody{
+		Intent:        "TASK",
+		Content:       "Hello encrypted world!",
+		Capability:    "some-cap",
+		CorrelationID: "corr-123",
+	}
+	envelope := makeEnvelopeGo(t, originalBody)
+
+	sealed, err := protocol7h3.SealEnvelope(envelope, recipientPub, senderPriv)
+	if err != nil {
+		t.Fatalf("SealEnvelope: %v", err)
+	}
+
+	_, body, err := protocol7h3.OpenEnvelope(sealed, recipientPriv, senderPub)
+	if err != nil {
+		t.Fatalf("OpenEnvelope: %v", err)
+	}
+
+	if body.Intent != originalBody.Intent {
+		t.Errorf("intent = %q, want %q", body.Intent, originalBody.Intent)
+	}
+	if body.Content != originalBody.Content {
+		t.Errorf("content = %q, want %q", body.Content, originalBody.Content)
+	}
+	if body.Capability != originalBody.Capability {
+		t.Errorf("capability = %q, want %q", body.Capability, originalBody.Capability)
+	}
+	if body.CorrelationID != originalBody.CorrelationID {
+		t.Errorf("correlationId = %q, want %q", body.CorrelationID, originalBody.CorrelationID)
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Test 3: OpenEnvelope fails with wrong recipient key
+// ---------------------------------------------------------------------------
+
+func TestOpenEnvelopeWrongRecipientKey(t *testing.T) {
+	recipientPub, _, err := protocol7h3.GenerateX25519KeyPair()
+	if err != nil {
+		t.Fatalf("GenerateX25519KeyPair: %v", err)
+	}
+	_, wrongPriv, err := protocol7h3.GenerateX25519KeyPair()
+	if err != nil {
+		t.Fatalf("GenerateX25519KeyPair wrong: %v", err)
+	}
+	senderPub, senderPriv, err := protocol7h3.GenerateKeypair()
+	if err != nil {
+		t.Fatalf("GenerateKeypair: %v", err)
+	}
+
+	envelope := makeEnvelopeGo(t, protocol7h3.ProtocolBody{Intent: "PING", Content: "secret"})
+	sealed, err := protocol7h3.SealEnvelope(envelope, recipientPub, senderPriv)
+	if err != nil {
+		t.Fatalf("SealEnvelope: %v", err)
+	}
+
+	// Wrong recipient private key — we need to test decryptBody path directly.
+	// To bypass signature check (which uses senderPub correctly), we test OpenEnvelope
+	// with wrong key but correct signature — the AEAD tag will fail.
+	// However, OpenEnvelope verifies Ed25519 first using senderPub (which matches),
+	// so signature passes, and then decryption fails with wrong key.
+	_, _, err = protocol7h3.OpenEnvelope(sealed, wrongPriv, senderPub)
+	if err == nil {
+		t.Error("expected error with wrong recipient key, got nil")
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Test 4: OpenEnvelope fails if envelope signature tampered
+// ---------------------------------------------------------------------------
+
+func TestOpenEnvelopeTamperedSignature(t *testing.T) {
+	recipientPub, recipientPriv, err := protocol7h3.GenerateX25519KeyPair()
+	if err != nil {
+		t.Fatalf("GenerateX25519KeyPair: %v", err)
+	}
+	senderPub, senderPriv, err := protocol7h3.GenerateKeypair()
+	if err != nil {
+		t.Fatalf("GenerateKeypair: %v", err)
+	}
+
+	envelope := makeEnvelopeGo(t, protocol7h3.ProtocolBody{Intent: "PING", Content: "secret"})
+	sealed, err := protocol7h3.SealEnvelope(envelope, recipientPub, senderPriv)
+	if err != nil {
+		t.Fatalf("SealEnvelope: %v", err)
+	}
+
+	// Tamper with signature
+	tamperedSig := *sealed.Signature
+	tamperedSig.Value = strings.Repeat("A", 86)
+	sealed.Signature = &tamperedSig
+
+	_, _, err = protocol7h3.OpenEnvelope(sealed, recipientPriv, senderPub)
+	if err == nil {
+		t.Error("expected error with tampered signature, got nil")
+	}
+	if !strings.Contains(err.Error(), "signature") {
+		t.Errorf("expected signature error, got: %v", err)
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Test 5: OpenEnvelope fails if ciphertext tampered (AEAD auth tag fails)
+// ---------------------------------------------------------------------------
+
+func TestOpenEnvelopeTamperedCiphertext(t *testing.T) {
+	recipientPub, recipientPriv, err := protocol7h3.GenerateX25519KeyPair()
+	if err != nil {
+		t.Fatalf("GenerateX25519KeyPair: %v", err)
+	}
+	senderPub, senderPriv, err := protocol7h3.GenerateKeypair()
+	if err != nil {
+		t.Fatalf("GenerateKeypair: %v", err)
+	}
+
+	envelope := makeEnvelopeGo(t, protocol7h3.ProtocolBody{Intent: "PING", Content: "secret"})
+	sealed, err := protocol7h3.SealEnvelope(envelope, recipientPub, senderPriv)
+	if err != nil {
+		t.Fatalf("SealEnvelope: %v", err)
+	}
+
+	// Decode the encrypted payload, flip a bit in ciphertext
+	payloadJSON, err := base64.RawURLEncoding.DecodeString(sealed.Body.Content)
+	if err != nil {
+		t.Fatalf("decode content: %v", err)
+	}
+	var payload map[string]string
+	if err = json.Unmarshal(payloadJSON, &payload); err != nil {
+		t.Fatalf("unmarshal payload: %v", err)
+	}
+	ctBytes, err := base64.RawURLEncoding.DecodeString(payload["ciphertext"])
+	if err != nil {
+		t.Fatalf("decode ciphertext: %v", err)
+	}
+	ctBytes[0] ^= 0xFF
+	payload["ciphertext"] = base64.RawURLEncoding.EncodeToString(ctBytes)
+
+	tamperedPayloadJSON, _ := json.Marshal(payload)
+	tamperedContent := base64.RawURLEncoding.EncodeToString(tamperedPayloadJSON)
+
+	// We need to test decryptBody path, bypassing the signature check by calling
+	// a sealed envelope that we signed correctly but with tampered content.
+	// Since we can't re-sign (that would require a new seal), test via a helper approach:
+	// Create a new sealed envelope with the tampered content re-signed.
+	tamperedEnv := sealed
+	tamperedEnv.Body.Content = tamperedContent
+	// Re-sign it so sig check passes but AEAD fails
+	reSealed, err := protocol7h3.SignEnvelopeEd25519(protocol7h3.ProtocolEnvelope{
+		Header: tamperedEnv.Header,
+		Body:   tamperedEnv.Body,
+	}, senderPriv)
+	if err != nil {
+		t.Fatalf("re-sign tampered envelope: %v", err)
+	}
+
+	_, _, err = protocol7h3.OpenEnvelope(reSealed, recipientPriv, senderPub)
+	if err == nil {
+		t.Error("expected error with tampered ciphertext, got nil")
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Test 6: Two SealEnvelope calls on same body produce different ciphertexts
+// ---------------------------------------------------------------------------
+
+func TestSealEnvelopeEphemeralRandomness(t *testing.T) {
+	recipientPub, _, err := protocol7h3.GenerateX25519KeyPair()
+	if err != nil {
+		t.Fatalf("GenerateX25519KeyPair: %v", err)
+	}
+	_, senderPriv, err := protocol7h3.GenerateKeypair()
+	if err != nil {
+		t.Fatalf("GenerateKeypair: %v", err)
+	}
+
+	body := protocol7h3.ProtocolBody{Intent: "PING", Content: "same content"}
+	envelope1 := makeEnvelopeGo(t, body)
+	envelope2 := makeEnvelopeGo(t, body)
+
+	sealed1, err := protocol7h3.SealEnvelope(envelope1, recipientPub, senderPriv)
+	if err != nil {
+		t.Fatalf("SealEnvelope 1: %v", err)
+	}
+	sealed2, err := protocol7h3.SealEnvelope(envelope2, recipientPub, senderPriv)
+	if err != nil {
+		t.Fatalf("SealEnvelope 2: %v", err)
+	}
+
+	if sealed1.Body.Content == sealed2.Body.Content {
+		t.Error("two seal calls produced identical ciphertexts — ephemeral key randomness failure")
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Test 7: Encrypted content is opaque (does not contain original body.content)
+// ---------------------------------------------------------------------------
+
+func TestEncryptedContentIsOpaque(t *testing.T) {
+	recipientPub, _, err := protocol7h3.GenerateX25519KeyPair()
+	if err != nil {
+		t.Fatalf("GenerateX25519KeyPair: %v", err)
+	}
+	_, senderPriv, err := protocol7h3.GenerateKeypair()
+	if err != nil {
+		t.Fatalf("GenerateKeypair: %v", err)
+	}
+
+	originalContent := "super-secret-data-12345"
+	envelope := makeEnvelopeGo(t, protocol7h3.ProtocolBody{Intent: "TASK", Content: originalContent})
+
+	sealed, err := protocol7h3.SealEnvelope(envelope, recipientPub, senderPriv)
+	if err != nil {
+		t.Fatalf("SealEnvelope: %v", err)
+	}
+
+	// The raw encrypted content should not contain the original plaintext
+	if strings.Contains(sealed.Body.Content, originalContent) {
+		t.Error("encrypted content contains original plaintext (raw base64url)")
+	}
+
+	// Decoded JSON of encrypted payload should also not contain it
+	payloadJSON, _ := base64.RawURLEncoding.DecodeString(sealed.Body.Content)
+	if strings.Contains(string(payloadJSON), originalContent) {
+		t.Error("encrypted payload JSON contains original plaintext")
+	}
+}

package/sdk/go/go.mod

@@ -1,3 +1,7 @@
 module github.com/IceMasterT/7h3-protocol/sdk/go
 
-go 1.21
+go 1.25.0
+
+require golang.org/x/crypto v0.53.0
+
+require golang.org/x/sys v0.46.0 // indirect

package/sdk/go/go.sum

@@ -0,0 +1,4 @@
+golang.org/x/crypto v0.53.0 h1:QZ4Muo8THX6CizN2vPPd5fBGHyogrdK9fG4wLPFUsto=
+golang.org/x/crypto v0.53.0/go.mod h1:DNLU434OwVakk9PzuwV8w62mAJpRJL3vsgcfp4Qnsio=
+golang.org/x/sys v0.46.0 h1:noSf2Fq6F8DBgS+LysIkx7rIExoNHJsxOAtPp4rthXw=
+golang.org/x/sys v0.46.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=

package/sdk/go/replay.go

@@ -0,0 +1,121 @@
+package protocol7h3
+
+import (
+	"context"
+	"sync"
+	"time"
+)
+
+// ---------------------------------------------------------------------------
+// ReplayStore interface
+// ---------------------------------------------------------------------------
+
+// ReplayStore provides atomic nonce deduplication for replay protection.
+//
+// Check atomically marks a nonce as seen and reports whether it was already
+// present:
+//   - (false, nil) — nonce is fresh (first time seen)
+//   - (true, nil)  — nonce is a replay (already seen)
+//   - (_, err)     — store error; caller should fail closed
+type ReplayStore interface {
+	Check(ctx context.Context, key string, ttlMs int64) (bool, error)
+}
+
+// ---------------------------------------------------------------------------
+// InMemoryReplayStore
+// ---------------------------------------------------------------------------
+
+type inMemoryEntry struct {
+	expiresAt time.Time
+}
+
+// InMemoryReplayStore is a stdlib-only, process-local replay store backed by
+// sync.Map with time-based expiry.  It does NOT provide cross-instance replay
+// protection — use RedisReplayStore for multi-instance deployments.
+type InMemoryReplayStore struct {
+	entries sync.Map
+	now     func() time.Time
+}
+
+// NewInMemoryReplayStore returns a new in-process replay store.
+func NewInMemoryReplayStore() *InMemoryReplayStore {
+	return &InMemoryReplayStore{now: time.Now}
+}
+
+// Check returns (false, nil) when the nonce is fresh and (true, nil) when it
+// is a replay.  Expired entries are evicted lazily on access.
+func (s *InMemoryReplayStore) Check(ctx context.Context, key string, ttlMs int64) (bool, error) {
+	ttl := time.Duration(ttlMs) * time.Millisecond
+	if ttl <= 0 {
+		ttl = time.Millisecond
+	}
+	now := s.now()
+	expiresAt := now.Add(ttl)
+
+	actual, loaded := s.entries.LoadOrStore(key, &inMemoryEntry{expiresAt: expiresAt})
+	if !loaded {
+		// Key was freshly stored — this is the first time we've seen it.
+		return false, nil
+	}
+
+	// Key already existed — check whether the stored entry is still live.
+	entry := actual.(*inMemoryEntry)
+	if now.After(entry.expiresAt) {
+		// Expired: treat as fresh and refresh the expiry.
+		s.entries.Store(key, &inMemoryEntry{expiresAt: expiresAt})
+		return false, nil
+	}
+
+	// Entry is live — this is a replay.
+	return true, nil
+}
+
+// ---------------------------------------------------------------------------
+// RedisReplayStore — injection-based, zero external imports
+// ---------------------------------------------------------------------------
+
+// SetNXFunc is the injection point for Redis SET NX PX semantics.
+//
+// Implementations should:
+//   - Return (true, nil)  when the key was newly set (fresh).
+//   - Return (false, nil) when the key already existed (replay blocked by NX).
+//   - Return (_, err)     on connection or protocol errors.
+//
+// Example adapter using go-redis:
+//
+//	func(ctx context.Context, key string, ttl time.Duration) (bool, error) {
+//	    return rdb.SetNX(ctx, key, "1", ttl).Result()
+//	}
+type SetNXFunc func(ctx context.Context, key string, ttl time.Duration) (bool, error)
+
+// RedisReplayStore delegates SET NX PX to an injected function, keeping this
+// package free of any Redis client dependency.
+type RedisReplayStore struct {
+	prefix string
+	setNX  SetNXFunc
+}
+
+// NewRedisReplayStore creates a RedisReplayStore.
+//
+// prefix is prepended to every nonce key (e.g. "7h3:nonce:").
+// setNX is the injection function described by SetNXFunc.
+func NewRedisReplayStore(prefix string, setNX SetNXFunc) *RedisReplayStore {
+	return &RedisReplayStore{prefix: prefix, setNX: setNX}
+}
+
+// Check returns (false, nil) when the nonce is fresh, (true, nil) when it is
+// a replay, or (false, err) on store error.
+func (r *RedisReplayStore) Check(ctx context.Context, key string, ttlMs int64) (bool, error) {
+	ttl := time.Duration(ttlMs) * time.Millisecond
+	if ttl <= 0 {
+		ttl = time.Millisecond
+	}
+
+	wasSet, err := r.setNX(ctx, r.prefix+key, ttl)
+	if err != nil {
+		return false, err
+	}
+	// wasSet=true → key newly set → fresh → not a replay
+	// wasSet=false → key existed → replay
+	return !wasSet, nil
+}

package/sdk/go/replay_test.go

@@ -0,0 +1,149 @@
+package protocol7h3
+
+import (
+	"context"
+	"sync"
+	"testing"
+	"time"
+)
+
+func TestInMemoryReplayStore_Fresh(t *testing.T) {
+	store := NewInMemoryReplayStore()
+	ctx := context.Background()
+
+	replay, err := store.Check(ctx, "nonce-1", 30_000)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if replay {
+		t.Error("expected fresh (false) on first call, got true")
+	}
+}
+
+func TestInMemoryReplayStore_Replay(t *testing.T) {
+	store := NewInMemoryReplayStore()
+	ctx := context.Background()
+
+	if _, err := store.Check(ctx, "nonce-2", 30_000); err != nil {
+		t.Fatalf("unexpected error on first call: %v", err)
+	}
+
+	replay, err := store.Check(ctx, "nonce-2", 30_000)
+	if err != nil {
+		t.Fatalf("unexpected error on second call: %v", err)
+	}
+	if !replay {
+		t.Error("expected replay (true) on second call with same nonce, got false")
+	}
+}
+
+func TestInMemoryReplayStore_ExpiredEntryTreatedAsFresh(t *testing.T) {
+	var mu sync.Mutex
+	now := time.Now()
+	store := &InMemoryReplayStore{
+		now: func() time.Time {
+			mu.Lock()
+			defer mu.Unlock()
+			return now
+		},
+	}
+	ctx := context.Background()
+
+	// First call: set nonce with 100ms TTL
+	replay, err := store.Check(ctx, "nonce-exp", 100)
+	if err != nil || replay {
+		t.Fatalf("expected fresh on first call; replay=%v err=%v", replay, err)
+	}
+
+	// Advance past TTL
+	mu.Lock()
+	now = now.Add(200 * time.Millisecond)
+	mu.Unlock()
+
+	// Second call: expired entry should be treated as fresh
+	replay, err = store.Check(ctx, "nonce-exp", 100)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if replay {
+		t.Error("expected fresh (false) after TTL expiry, got true")
+	}
+}
+
+func TestInMemoryReplayStore_DistinctNonces(t *testing.T) {
+	store := NewInMemoryReplayStore()
+	ctx := context.Background()
+
+	for _, nonce := range []string{"a", "b", "c"} {
+		replay, err := store.Check(ctx, nonce, 60_000)
+		if err != nil || replay {
+			t.Errorf("nonce %q: expected fresh; replay=%v err=%v", nonce, replay, err)
+		}
+	}
+}
+
+func TestRedisReplayStore_Fresh(t *testing.T) {
+	// setNX returns true = key was newly set = fresh
+	setNX := func(_ context.Context, _ string, _ time.Duration) (bool, error) {
+		return true, nil
+	}
+	store := NewRedisReplayStore("7h3:nonce:", setNX)
+	replay, err := store.Check(context.Background(), "nonce-r1", 30_000)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if replay {
+		t.Error("expected fresh (false) when setNX returns true")
+	}
+}
+
+func TestRedisReplayStore_Replay(t *testing.T) {
+	// setNX returns false = key already existed = replay
+	setNX := func(_ context.Context, _ string, _ time.Duration) (bool, error) {
+		return false, nil
+	}
+	store := NewRedisReplayStore("7h3:nonce:", setNX)
+	replay, err := store.Check(context.Background(), "nonce-r2", 30_000)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !replay {
+		t.Error("expected replay (true) when setNX returns false")
+	}
+}
+
+func TestRedisReplayStore_KeyPrefix(t *testing.T) {
+	var capturedKey string
+	setNX := func(_ context.Context, key string, _ time.Duration) (bool, error) {
+		capturedKey = key
+		return true, nil
+	}
+	store := NewRedisReplayStore("custom:prefix:", setNX)
+	_, _ = store.Check(context.Background(), "my-nonce", 5000)
+
+	if capturedKey != "custom:prefix:my-nonce" {
+		t.Errorf("expected key 'custom:prefix:my-nonce', got %q", capturedKey)
+	}
+}
+
+func TestRedisReplayStore_TTLClamped(t *testing.T) {
+	var capturedTTL time.Duration
+	setNX := func(_ context.Context, _ string, ttl time.Duration) (bool, error) {
+		capturedTTL = ttl
+		return true, nil
+	}
+	store := NewRedisReplayStore("p:", setNX)
+	_, _ = store.Check(context.Background(), "n", 0)
+
+	if capturedTTL < time.Millisecond {
+		t.Errorf("TTL should be clamped to at least 1ms, got %v", capturedTTL)
+	}
+}
+
+func TestRedisReplayStore_ImplementsInterface(t *testing.T) {
+	setNX := func(_ context.Context, _ string, _ time.Duration) (bool, error) {
+		return true, nil
+	}
+	var _ ReplayStore = NewRedisReplayStore("p:", setNX)
+	var _ ReplayStore = NewInMemoryReplayStore()
+}