@7h3/protocol 0.1.2 → 0.4.0

package/sdk/go/protocol_test.go

@@ -0,0 +1,334 @@
+package protocol7h3
+
+import (
+	"crypto/ed25519"
+	"crypto/x509"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"strconv"
+	"strings"
+	"testing"
+	"time"
+)
+
+// Test 1: CanonicalizeEnvelope matches the conformance vector exactly.
+func TestCanonicalizeEnvelopeConformanceVector(t *testing.T) {
+	h := ProtocolHeader{
+		Version:     "7h3/0.1",
+		MessageID:   "vec-1",
+		Nonce:       "nonce-vec-1",
+		Sender:      "agent.alpha",
+		Recipient:   "agent.beta",
+		TimestampMs: 1712500000000,
+		TTLMs:       60000,
+	}
+	b := ProtocolBody{
+		Intent:        "TASK",
+		Content:       "route:alpha->beta",
+		Capability:    "task.plan",
+		CorrelationID: "corr-1",
+	}
+
+	expected := `{"body":{"capability":"task.plan","content":"route:alpha->beta","correlationId":"corr-1","intent":"TASK"},"header":{"messageId":"vec-1","nonce":"nonce-vec-1","recipient":"agent.beta","sender":"agent.alpha","timestampMs":1712500000000,"ttlMs":60000,"version":"7h3/0.1"}}`
+	got := CanonicalizeEnvelope(h, b)
+
+	if got != expected {
+		t.Errorf("canonical mismatch:\ngot:  %s\nwant: %s", got, expected)
+	}
+}
+
+// Test 2: CanonicalizeEnvelope with no optional fields.
+func TestCanonicalizeEnvelopeNoOptionals(t *testing.T) {
+	h := ProtocolHeader{
+		Version:     "7h3/0.1",
+		MessageID:   "msg-1",
+		Nonce:       "nonce-1",
+		Sender:      "agent.a",
+		TimestampMs: 1000000,
+		TTLMs:       30000,
+	}
+	b := ProtocolBody{
+		Intent:  "PING",
+		Content: "hello",
+	}
+
+	got := CanonicalizeEnvelope(h, b)
+
+	// Must not contain recipient, capability, correlationId keys
+	if strings.Contains(got, "recipient") {
+		t.Errorf("canonical should not contain 'recipient' when empty: %s", got)
+	}
+	if strings.Contains(got, "capability") {
+		t.Errorf("canonical should not contain 'capability' when empty: %s", got)
+	}
+	if strings.Contains(got, "correlationId") {
+		t.Errorf("canonical should not contain 'correlationId' when empty: %s", got)
+	}
+
+	// Verify it's valid JSON
+	var v interface{}
+	if err := json.Unmarshal([]byte(got), &v); err != nil {
+		t.Errorf("canonical is not valid JSON: %v\n%s", err, got)
+	}
+}
+
+// Test 3: GenerateKeypair returns non-empty strings.
+func TestGenerateKeypair(t *testing.T) {
+	pub, priv, err := GenerateKeypair()
+	if err != nil {
+		t.Fatalf("GenerateKeypair error: %v", err)
+	}
+	if pub == "" {
+		t.Error("public key is empty")
+	}
+	if priv == "" {
+		t.Error("private key is empty")
+	}
+}
+
+// Test 4: SignEnvelopeEd25519 + VerifyEnvelopeEd25519 round trip.
+func TestSignVerifyEd25519RoundTrip(t *testing.T) {
+	pub, priv, err := GenerateKeypair()
+	if err != nil {
+		t.Fatalf("GenerateKeypair: %v", err)
+	}
+
+	env := CreateEnvelope("agent.a", "agent.b", 60000, ProtocolBody{
+		Intent:  "TASK",
+		Content: "hello",
+	})
+
+	signed, err := SignEnvelopeEd25519(env, priv)
+	if err != nil {
+		t.Fatalf("SignEnvelopeEd25519: %v", err)
+	}
+
+	ok, err := VerifyEnvelopeEd25519(signed, pub)
+	if err != nil {
+		t.Fatalf("VerifyEnvelopeEd25519: %v", err)
+	}
+	if !ok {
+		t.Error("expected verification to succeed")
+	}
+}
+
+// Test 5: VerifyEnvelopeEd25519 tampered envelope returns false.
+func TestVerifyEd25519Tampered(t *testing.T) {
+	pub, priv, err := GenerateKeypair()
+	if err != nil {
+		t.Fatalf("GenerateKeypair: %v", err)
+	}
+
+	env := CreateEnvelope("agent.a", "agent.b", 60000, ProtocolBody{
+		Intent:  "TASK",
+		Content: "hello",
+	})
+
+	signed, err := SignEnvelopeEd25519(env, priv)
+	if err != nil {
+		t.Fatalf("SignEnvelopeEd25519: %v", err)
+	}
+
+	// Tamper with the body content
+	signed.Body.Content = "tampered"
+
+	ok, err := VerifyEnvelopeEd25519(signed, pub)
+	if err != nil {
+		t.Fatalf("VerifyEnvelopeEd25519: %v", err)
+	}
+	if ok {
+		t.Error("expected verification to fail for tampered envelope")
+	}
+}
+
+// Test 6: SignEnvelopeHmac + VerifyEnvelopeHmac round trip.
+func TestSignVerifyHmacRoundTrip(t *testing.T) {
+	secret := "super-secret-key"
+	env := CreateEnvelope("agent.a", "agent.b", 60000, ProtocolBody{
+		Intent:  "PING",
+		Content: "ping",
+	})
+
+	signed, err := SignEnvelopeHmac(env, secret, "key-1")
+	if err != nil {
+		t.Fatalf("SignEnvelopeHmac: %v", err)
+	}
+
+	ok, err := VerifyEnvelopeHmac(signed, secret)
+	if err != nil {
+		t.Fatalf("VerifyEnvelopeHmac: %v", err)
+	}
+	if !ok {
+		t.Error("expected HMAC verification to succeed")
+	}
+}
+
+// Test 7: ValidateEnvelope expired returns error diagnostic.
+func TestValidateEnvelopeExpired(t *testing.T) {
+	env := ProtocolEnvelope{
+		Header: ProtocolHeader{
+			Version:     WireVersion,
+			MessageID:   "msg-old",
+			Nonce:       "nonce-old",
+			Sender:      "agent.a",
+			TimestampMs: time.Now().UnixMilli() - 120000, // 2 minutes ago
+			TTLMs:       60000,                           // 1 minute TTL → expired
+		},
+		Body: ProtocolBody{
+			Intent:  "PING",
+			Content: "old",
+		},
+	}
+
+	diags := ValidateEnvelope(env)
+	found := false
+	for _, d := range diags {
+		if d.Message == "Message TTL expired" {
+			found = true
+			break
+		}
+	}
+	if !found {
+		t.Errorf("expected 'Message TTL expired' diagnostic, got: %+v", diags)
+	}
+}
+
+// Test 8: HTTP: VerifyHTTPEnvelope valid signed request.
+func TestHTTPVerifyValidSignedRequest(t *testing.T) {
+	pub, priv, err := GenerateKeypair()
+	if err != nil {
+		t.Fatalf("GenerateKeypair: %v", err)
+	}
+
+	env := CreateEnvelope("agent.a", "agent.b", 60000, ProtocolBody{
+		Intent:  "TASK",
+		Content: "do something",
+	})
+
+	signed, err := SignEnvelopeEd25519(env, priv)
+	if err != nil {
+		t.Fatalf("SignEnvelopeEd25519: %v", err)
+	}
+
+	b, err := json.Marshal(signed)
+	if err != nil {
+		t.Fatalf("json.Marshal: %v", err)
+	}
+
+	req := httptest.NewRequest(http.MethodPost, "/", nil)
+	req.Header.Set(HTTPEnvelopeHeader, string(b))
+
+	registry := &StaticKeyRegistry{Keys: map[string]string{"agent.a": pub}}
+	result := VerifyHTTPEnvelope(req, registry)
+
+	if !result.OK {
+		t.Errorf("expected OK=true, got reason=%s detail=%s", result.Reason, result.Detail)
+	}
+}
+
+// Test 9: HTTP: VerifyHTTPEnvelope missing header returns ReasonMissingHeader.
+func TestHTTPVerifyMissingHeader(t *testing.T) {
+	req := httptest.NewRequest(http.MethodPost, "/", nil)
+	registry := &StaticKeyRegistry{Keys: map[string]string{}}
+	result := VerifyHTTPEnvelope(req, registry)
+
+	if result.OK {
+		t.Error("expected OK=false")
+	}
+	if result.Reason != ReasonMissingHeader {
+		t.Errorf("expected reason=%s got=%s", ReasonMissingHeader, result.Reason)
+	}
+}
+
+// Test 10: Webhook: SignWebhook + VerifyWebhook round trip.
+func TestWebhookSignVerifyRoundTrip(t *testing.T) {
+	pub, priv, err := GenerateKeypair()
+	if err != nil {
+		t.Fatalf("GenerateKeypair: %v", err)
+	}
+
+	body := `{"event":"order.created","id":"ord-1"}`
+	sig, tsMs, err := SignWebhook(body, priv)
+	if err != nil {
+		t.Fatalf("SignWebhook: %v", err)
+	}
+
+	ok, err := VerifyWebhook(body, sig, tsMs, pub)
+	if err != nil {
+		t.Fatalf("VerifyWebhook: %v", err)
+	}
+	if !ok {
+		t.Error("expected webhook verification to succeed")
+	}
+}
+
+// signWithTimestamp is a test helper that signs a webhook payload with a specific timestamp.
+func signWithTimestamp(body, privKeyBase64Url string, tsMs int64) (string, error) {
+	privDER, err := decodeBase64Url(privKeyBase64Url)
+	if err != nil {
+		return "", fmt.Errorf("decode: %w", err)
+	}
+	privKeyIface, err := x509.ParsePKCS8PrivateKey(privDER)
+	if err != nil {
+		return "", fmt.Errorf("parse: %w", err)
+	}
+	edPriv, ok := privKeyIface.(ed25519.PrivateKey)
+	if !ok {
+		return "", fmt.Errorf("not ed25519")
+	}
+	payload := webhookPayload(tsMs, body)
+	sigBytes := ed25519.Sign(edPriv, []byte(payload))
+	return encodeBase64Url(sigBytes), nil
+}
+
+// Test 11: Webhook: expired timestamp returns false.
+func TestWebhookExpiredTimestamp(t *testing.T) {
+	pub, priv, err := GenerateKeypair()
+	if err != nil {
+		t.Fatalf("GenerateKeypair: %v", err)
+	}
+
+	body := `{"event":"test"}`
+
+	// Create a signature with a timestamp 10 minutes in the past
+	oldTs := time.Now().UnixMilli() - 600000
+	sig, err := signWithTimestamp(body, priv, oldTs)
+	if err != nil {
+		t.Fatalf("signWithTimestamp: %v", err)
+	}
+	tsStr := strconv.FormatInt(oldTs, 10)
+
+	ok, err := VerifyWebhook(body, sig, tsStr, pub, WebhookDefaultTTLMs)
+	if err != nil {
+		t.Fatalf("VerifyWebhook: %v", err)
+	}
+	if ok {
+		t.Error("expected expired webhook to return false")
+	}
+}
+
+// Test 12: Webhook: tampered body returns false.
+func TestWebhookTamperedBody(t *testing.T) {
+	pub, priv, err := GenerateKeypair()
+	if err != nil {
+		t.Fatalf("GenerateKeypair: %v", err)
+	}
+
+	body := `{"event":"order.created"}`
+	sig, tsMs, err := SignWebhook(body, priv)
+	if err != nil {
+		t.Fatalf("SignWebhook: %v", err)
+	}
+
+	// Tamper with body
+	tamperedBody := `{"event":"order.deleted"}`
+	ok, err := VerifyWebhook(tamperedBody, sig, tsMs, pub)
+	if err != nil {
+		t.Fatalf("VerifyWebhook: %v", err)
+	}
+	if ok {
+		t.Error("expected tampered webhook body to return false")
+	}
+}

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

package/sdk/python/README.md

@@ -0,0 +1,18 @@
+# 7h3 Protocol AIP Python SDK (Skeleton)
+
+Minimal reference SDK for `aip/0.1` parity with the TypeScript implementation.
+
+## Included
+
+- deterministic canonicalization
+- HS256 HMAC signing and verification
+- ED25519 signing and verification (requires `cryptography` package)
+- compact wire encode/decode
+- envelope validation helpers (version, required fields, TTL)
+- conformance tests using shared vectors from `conformance/aip_v0_1.json`
+
+## Run conformance tests
+
+```bash
+PYTHONPATH=sdk/python python3 -m unittest discover -s sdk/python/tests -v
+```

package/sdk/python/protocol_7h3/__init__.py

@@ -0,0 +1,46 @@
+from .protocol import (  # noqa: F401
+    canonicalize_envelope,
+    decode_envelope,
+    encode_envelope_compact,
+    sign_canonical_payload_ed25519,
+    sign_canonical_payload_hmac,
+    sign_envelope_ed25519,
+    sign_envelope_hmac,
+    validate_envelope,
+    verify_canonical_payload_ed25519,
+    verify_canonical_payload_hmac,
+    verify_envelope_ed25519,
+    verify_envelope_hmac,
+)
+
+try:
+    from .http import (  # noqa: F401
+        DEFAULT_HEADER, KeyRegistry, StaticKeyRegistry,
+        verify_http_envelope, sign_http_request, build_signed_request_headers,
+    )
+except ImportError:
+    pass
+
+try:
+    from .webhook import (  # noqa: F401
+        WEBHOOK_SIG_HEADER, WEBHOOK_TS_HEADER,
+        sign_webhook, sign_webhook_hmac, verify_webhook, verify_webhook_hmac, consume_webhook,
+    )
+except ImportError:
+    pass
+
+try:
+    from .queue import (  # noqa: F401
+        sign_queue_message, verify_queue_message, verify_queue_batch,
+    )
+except ImportError:
+    pass
+
+try:
+    from .keys import (  # noqa: F401
+        KeyEntry, WellKnownKeysDocument, ManagedKeyPair,
+        KeyRotationManager, RevocationRegistry,
+        fetch_well_known_keys,
+    )
+except ImportError:
+    pass