@7h3/protocol 0.1.2 → 0.5.0

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()
+}

package/sdk/go/webhook.go

@@ -0,0 +1,136 @@
+package protocol7h3
+
+import (
+	"crypto/ed25519"
+	"crypto/hmac"
+	"crypto/sha256"
+	"crypto/x509"
+	"fmt"
+	"strconv"
+	"time"
+)
+
+// WebhookSigHeader is the HTTP header carrying the webhook signature.
+const WebhookSigHeader = "X-7h3-Sig"
+
+// WebhookTsHeader is the HTTP header carrying the webhook timestamp.
+const WebhookTsHeader = "X-7h3-Ts"
+
+// WebhookDefaultTTLMs is the default maximum age for webhook signatures.
+const WebhookDefaultTTLMs int64 = 300_000
+
+// webhookPayload constructs the signed payload: "<tsMs>.<body>"
+func webhookPayload(tsMs int64, body string) string {
+	return fmt.Sprintf("%d.%s", tsMs, body)
+}
+
+// SignWebhook signs a webhook body with an Ed25519 private key (PKCS8 base64url).
+// Returns sig (base64url) and tsMs (string timestamp milliseconds).
+func SignWebhook(body, privateKeyPkcs8Base64Url string) (sig, tsMs string, err error) {
+	privDER, err := decodeBase64Url(privateKeyPkcs8Base64Url)
+	if err != nil {
+		return "", "", fmt.Errorf("protocol7h3: decode private key: %w", err)
+	}
+
+	privKey, err := x509.ParsePKCS8PrivateKey(privDER)
+	if err != nil {
+		return "", "", fmt.Errorf("protocol7h3: parse private key: %w", err)
+	}
+
+	edPriv, ok := privKey.(ed25519.PrivateKey)
+	if !ok {
+		return "", "", fmt.Errorf("protocol7h3: key is not Ed25519")
+	}
+
+	nowMs := time.Now().UnixMilli()
+	payload := webhookPayload(nowMs, body)
+	sigBytes := ed25519.Sign(edPriv, []byte(payload))
+
+	return encodeBase64Url(sigBytes), strconv.FormatInt(nowMs, 10), nil
+}
+
+// VerifyWebhook verifies a webhook signature.
+// maxAgeMs defaults to WebhookDefaultTTLMs if not provided.
+func VerifyWebhook(body, sig, tsStr, publicKeySpkiBase64Url string, maxAgeMs ...int64) (bool, error) {
+	tsMs, err := strconv.ParseInt(tsStr, 10, 64)
+	if err != nil {
+		return false, fmt.Errorf("protocol7h3: invalid timestamp: %w", err)
+	}
+
+	maxAge := WebhookDefaultTTLMs
+	if len(maxAgeMs) > 0 {
+		maxAge = maxAgeMs[0]
+	}
+
+	nowMs := time.Now().UnixMilli()
+	if nowMs-tsMs > maxAge {
+		return false, nil
+	}
+
+	pubDER, err := decodeBase64Url(publicKeySpkiBase64Url)
+	if err != nil {
+		return false, fmt.Errorf("protocol7h3: decode public key: %w", err)
+	}
+
+	pubKey, err := x509.ParsePKIXPublicKey(pubDER)
+	if err != nil {
+		return false, fmt.Errorf("protocol7h3: parse public key: %w", err)
+	}
+
+	edPub, ok := pubKey.(ed25519.PublicKey)
+	if !ok {
+		return false, fmt.Errorf("protocol7h3: key is not Ed25519")
+	}
+
+	sigBytes, err := decodeBase64Url(sig)
+	if err != nil {
+		return false, fmt.Errorf("protocol7h3: decode signature: %w", err)
+	}
+
+	payload := webhookPayload(tsMs, body)
+	return ed25519.Verify(edPub, []byte(payload), sigBytes), nil
+}
+
+// SignWebhookHmac signs a webhook body with HMAC-SHA256.
+// Returns sig (base64url) and tsMs (string timestamp milliseconds).
+func SignWebhookHmac(body, secret string) (sig, tsMs string, err error) {
+	nowMs := time.Now().UnixMilli()
+	payload := webhookPayload(nowMs, body)
+
+	mac := hmac.New(sha256.New, []byte(secret))
+	mac.Write([]byte(payload))
+	sigBytes := mac.Sum(nil)
+
+	return encodeBase64Url(sigBytes), strconv.FormatInt(nowMs, 10), nil
+}
+
+// VerifyWebhookHmac verifies a webhook HMAC-SHA256 signature.
+// maxAgeMs defaults to WebhookDefaultTTLMs if not provided.
+func VerifyWebhookHmac(body, sig, tsStr, secret string, maxAgeMs ...int64) (bool, error) {
+	tsMs, err := strconv.ParseInt(tsStr, 10, 64)
+	if err != nil {
+		return false, fmt.Errorf("protocol7h3: invalid timestamp: %w", err)
+	}
+
+	maxAge := WebhookDefaultTTLMs
+	if len(maxAgeMs) > 0 {
+		maxAge = maxAgeMs[0]
+	}
+
+	nowMs := time.Now().UnixMilli()
+	if nowMs-tsMs > maxAge {
+		return false, nil
+	}
+
+	sigBytes, err := decodeBase64Url(sig)
+	if err != nil {
+		return false, fmt.Errorf("protocol7h3: decode signature: %w", err)
+	}
+
+	payload := webhookPayload(tsMs, body)
+	mac := hmac.New(sha256.New, []byte(secret))
+	mac.Write([]byte(payload))
+	expected := mac.Sum(nil)
+
+	return hmac.Equal(expected, sigBytes), nil
+}