feat(auth): add service-level auth with sctx integration (#8)

* feat(auth): add service-level auth with sctx integration

Add mesh-level authentication infrastructure:
- Metadata type for sctx.Context[M] shared across all mesh services
- Keychain interface with FileKeychain for loading signing keys
- Admin helpers for bootstrapping sctx.Admin[Metadata]
- MeshAuth gRPC service (ExchangeToken, RevokeToken) built into every node
- Guard interceptors (unary + stream) validating tokens per-RPC method
- Node/NodeBuilder/Server wiring for auth, guards, and MeshAuth

Closes #7

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix(auth): address review findings — nodeToken, revocation auth, interface contract

- Generate node's own token during Build() via self-assertion exchange,
  making guard interceptors functional
- Enforce self-revocation in RevokeToken — caller can only revoke own token
- Add LoadTrustedCAs to Keychain interface, remove FileKeychain type assertion
- Fail hard in interceptor when CallerFromContext fails after guard pass
- Sanitize id with filepath.Base in FileKeychain to prevent path traversal
- Preserve existing GuardRegistry in Build() instead of unconditional overwrite
- Capture base policy once in DefaultMeshPolicy (avoid double invocation)
- Add //go:build testing tags to keychain_test.go, interceptor_test.go, metadata_test.go

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* feat(auth): add automatic token exchange in ServiceClientPool

ServiceClientPool now performs transparent token exchange when the node
has auth configured. On first connection to a target node, the pool
creates a signed assertion, calls MeshAuth.ExchangeToken, and attaches
the token to all outgoing calls via grpc.PerRPCCredentials.

Callers using ServiceClient.Get(ctx) get a fully authenticated client
with no manual token management.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: address CI lint findings — gosec nolint, errcheck, variable shadow

- Add nolint:gosec to tokenMetadataKey (metadata key, not credential)
- Add nolint:gosec to FileKeychain os.ReadFile calls (paths sanitized)
- Fix errcheck on tmpConn.Close() in client.go
- Fix variable shadow in ExchangeToken (err -> unmarshalErr)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: case-zbz

admin.go

@@ -0,0 +1,74 @@
+package aegis
+
+import (
+	"context"
+	"crypto"
+	"crypto/x509"
+	"fmt"
+	"time"
+
+	"github.com/zoobz-io/sctx"
+)
+
+// NewAdmin creates an sctx.Admin[Metadata] from a private key and trusted CA pool.
+func NewAdmin(privateKey crypto.PrivateKey, trustedCAs *x509.CertPool) (sctx.Admin[Metadata], error) {
+	admin, err := sctx.NewAdminService[Metadata](privateKey, trustedCAs)
+	if err != nil {
+		return nil, fmt.Errorf("failed to create admin: %w", err)
+	}
+
+	if err := admin.SetPolicy(DefaultMeshPolicy()); err != nil {
+		return nil, fmt.Errorf("failed to set policy: %w", err)
+	}
+
+	cache := sctx.NewBoundedMemoryCache[Metadata](sctx.CacheOptions{
+		MaxSize:         1000,
+		CleanupInterval: 5 * time.Minute,
+	})
+	if err := admin.SetCache(cache); err != nil {
+		return nil, fmt.Errorf("failed to set cache: %w", err)
+	}
+
+	return admin, nil
+}
+
+// NewAdminFromKeychain creates an Admin by loading keys from a Keychain.
+func NewAdminFromKeychain(ctx context.Context, keychain Keychain, id string) (sctx.Admin[Metadata], error) {
+	key, err := keychain.LoadPrivateKey(ctx, id)
+	if err != nil {
+		return nil, fmt.Errorf("failed to load private key: %w", err)
+	}
+
+	caPool, err := keychain.LoadTrustedCAs(ctx)
+	if err != nil {
+		return nil, fmt.Errorf("failed to load CA pool: %w", err)
+	}
+
+	return NewAdmin(key, caPool)
+}
+
+// DefaultMeshPolicy returns a ContextPolicy that populates Metadata from certificate fields.
+// CN → NodeID, O (first) → ServiceName.
+func DefaultMeshPolicy() sctx.ContextPolicy[Metadata] {
+	basePolicy := sctx.DefaultContextPolicy[Metadata]()
+	return func(cert *x509.Certificate) (*sctx.Context[Metadata], error) {
+		base, err := basePolicy(cert)
+		if err != nil {
+			return nil, err
+		}
+
+		base.Metadata = Metadata{
+			NodeID:      cert.Subject.CommonName,
+			ServiceName: firstOrEmpty(cert.Subject.Organization),
+		}
+
+		return base, nil
+	}
+}
+
+func firstOrEmpty(s []string) string {
+	if len(s) > 0 {
+		return s[0]
+	}
+	return ""
+}

admin_test.go

@@ -0,0 +1,128 @@
+//go:build testing
+
+package aegis
+
+import (
+	"context"
+	"crypto/ed25519"
+	"crypto/rand"
+	"crypto/x509"
+	"crypto/x509/pkix"
+	"math/big"
+	"testing"
+	"time"
+
+	"github.com/zoobz-io/sctx"
+)
+
+func TestNewAdmin(t *testing.T) {
+	sctx.ResetAdminForTesting()
+
+	priv, caPool := generateTestAdminDeps(t)
+
+	admin, err := NewAdmin(priv, caPool)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if admin == nil {
+		t.Fatal("expected non-nil admin")
+	}
+}
+
+func TestNewAdminFromKeychain(t *testing.T) {
+	sctx.ResetAdminForTesting()
+
+	dir := t.TempDir()
+	writeTestKey(t, dir, "node-1")
+	writeTestCACert(t, dir)
+
+	kc := NewFileKeychain(dir)
+	admin, err := NewAdminFromKeychain(context.Background(), kc, "node-1")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if admin == nil {
+		t.Fatal("expected non-nil admin")
+	}
+}
+
+func TestDefaultMeshPolicy(t *testing.T) {
+	policy := DefaultMeshPolicy()
+
+	pub, priv, err := ed25519.GenerateKey(rand.Reader)
+	if err != nil {
+		t.Fatalf("failed to generate key: %v", err)
+	}
+	_ = priv
+
+	template := &x509.Certificate{
+		SerialNumber: big.NewInt(1),
+		Subject: pkix.Name{
+			CommonName:   "node-1",
+			Organization: []string{"api-service"},
+		},
+		NotBefore: time.Now().Add(-time.Hour),
+		NotAfter:  time.Now().Add(24 * time.Hour),
+	}
+
+	certDER, err := x509.CreateCertificate(rand.Reader, template, template, pub, priv)
+	if err != nil {
+		t.Fatalf("failed to create cert: %v", err)
+	}
+
+	cert, err := x509.ParseCertificate(certDER)
+	if err != nil {
+		t.Fatalf("failed to parse cert: %v", err)
+	}
+
+	sc, err := policy(cert)
+	if err != nil {
+		t.Fatalf("policy returned error: %v", err)
+	}
+
+	if sc.Metadata.NodeID != "node-1" {
+		t.Errorf("expected NodeID 'node-1', got %q", sc.Metadata.NodeID)
+	}
+	if sc.Metadata.ServiceName != "api-service" {
+		t.Errorf("expected ServiceName 'api-service', got %q", sc.Metadata.ServiceName)
+	}
+}
+
+func generateTestAdminDeps(t *testing.T) (ed25519.PrivateKey, *x509.CertPool) {
+	t.Helper()
+
+	_, priv, err := ed25519.GenerateKey(rand.Reader)
+	if err != nil {
+		t.Fatalf("failed to generate key: %v", err)
+	}
+
+	caPub, caPriv, err := ed25519.GenerateKey(rand.Reader)
+	if err != nil {
+		t.Fatalf("failed to generate CA key: %v", err)
+	}
+
+	caTemplate := &x509.Certificate{
+		SerialNumber:          big.NewInt(1),
+		Subject:               pkix.Name{CommonName: "test-ca"},
+		NotBefore:             time.Now().Add(-time.Hour),
+		NotAfter:              time.Now().Add(24 * time.Hour),
+		IsCA:                  true,
+		BasicConstraintsValid: true,
+		KeyUsage:              x509.KeyUsageCertSign,
+	}
+
+	caCertDER, err := x509.CreateCertificate(rand.Reader, caTemplate, caTemplate, caPub, caPriv)
+	if err != nil {
+		t.Fatalf("failed to create CA cert: %v", err)
+	}
+
+	caCert, err := x509.ParseCertificate(caCertDER)
+	if err != nil {
+		t.Fatalf("failed to parse CA cert: %v", err)
+	}
+
+	pool := x509.NewCertPool()
+	pool.AddCert(caCert)
+
+	return priv, pool
+}

client.go

@@ -2,10 +2,15 @@ package aegis
 
 import (
 	"context"
+	"crypto/x509"
+	"encoding/json"
 	"errors"
+	"fmt"
 	"sync"
 	"sync/atomic"
+	"time"
 
+	"github.com/zoobz-io/sctx"
 	"google.golang.org/grpc"
 	"google.golang.org/grpc/credentials"
 )
@@ -59,7 +64,20 @@ func (p *ServiceClientPool) getOrCreateConn(ctx context.Context, address string)
 	}
 
 	creds := credentials.NewTLS(p.node.TLSConfig.GetClientTLSConfig(address))
-	conn, err := grpc.NewClient(address, grpc.WithTransportCredentials(creds))
+	opts := []grpc.DialOption{grpc.WithTransportCredentials(creds)}
+
+	// If the node has auth, exchange a token with the target and attach to outgoing calls
+	if p.node.Admin != nil && p.node.TLSConfig != nil {
+		tokenCreds, err := p.exchangeToken(ctx, address, creds)
+		if err != nil {
+			return nil, fmt.Errorf("token exchange with %s failed: %w", address, err)
+		}
+		if tokenCreds != nil {
+			opts = append(opts, grpc.WithPerRPCCredentials(tokenCreds))
+		}
+	}
+
+	conn, err := grpc.NewClient(address, opts...)
 	if err != nil {
 		return nil, err
 	}
@@ -154,3 +172,59 @@ func (sc *ServiceClient[T]) Get(ctx context.Context) (T, error) {
 	}
 	return sc.newClient(conn), nil
 }
+
+// exchangeToken creates a temporary connection to the target, calls MeshAuth.ExchangeToken,
+// and returns PerRPCCredentials that attach the token to outgoing calls.
+func (p *ServiceClientPool) exchangeToken(ctx context.Context, address string, transportCreds credentials.TransportCredentials) (*tokenCredentials, error) {
+	// Create a temporary connection for the token exchange
+	tmpConn, err := grpc.NewClient(address, grpc.WithTransportCredentials(transportCreds))
+	if err != nil {
+		return nil, fmt.Errorf("failed to connect for token exchange: %w", err)
+	}
+	defer func() { _ = tmpConn.Close() }()
+
+	// Get the node's TLS cert and private key for the assertion
+	cert, err := x509.ParseCertificate(p.node.TLSConfig.Certificate.Certificate[0])
+	if err != nil {
+		return nil, fmt.Errorf("failed to parse node certificate: %w", err)
+	}
+
+	assertion, err := sctx.CreateAssertion(p.node.TLSConfig.Certificate.PrivateKey, cert)
+	if err != nil {
+		return nil, fmt.Errorf("failed to create assertion: %w", err)
+	}
+
+	assertionBytes, err := json.Marshal(assertion)
+	if err != nil {
+		return nil, fmt.Errorf("failed to marshal assertion: %w", err)
+	}
+
+	client := NewMeshAuthClient(tmpConn)
+	resp, err := client.ExchangeToken(ctx, &TokenExchangeRequest{Assertion: assertionBytes})
+	if err != nil {
+		return nil, fmt.Errorf("token exchange RPC failed: %w", err)
+	}
+
+	return &tokenCredentials{
+		token:     resp.Token,
+		expiresAt: time.Unix(resp.ExpiresAt, 0),
+	}, nil
+}
+
+// tokenCredentials implements grpc.PerRPCCredentials to attach the aegis token
+// to outgoing gRPC metadata on every call.
+type tokenCredentials struct {
+	token     string
+	expiresAt time.Time
+}
+
+func (tc *tokenCredentials) GetRequestMetadata(_ context.Context, _ ...string) (map[string]string, error) {
+	if time.Now().After(tc.expiresAt) {
+		return nil, errors.New("aegis token expired")
+	}
+	return map[string]string{tokenMetadataKey: tc.token}, nil
+}
+
+func (tc *tokenCredentials) RequireTransportSecurity() bool {
+	return true
+}

go.mod

@@ -1,15 +1,17 @@
 module github.com/zoobz-io/aegis
 
-go 1.24
+go 1.24.0
 
 toolchain go1.25.5
 
 require (
+	github.com/zoobz-io/sctx v1.0.3
 	google.golang.org/grpc v1.74.2
 	google.golang.org/protobuf v1.36.6
 )
 
 require (
+	github.com/zoobz-io/capitan v1.0.2 // indirect
 	golang.org/x/net v0.40.0 // indirect
 	golang.org/x/sys v0.33.0 // indirect
 	golang.org/x/text v0.25.0 // indirect

go.sum

@@ -8,6 +8,10 @@ github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
 github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
 github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
 github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/zoobz-io/capitan v1.0.2 h1:/NKAgntWeRIN4S0oaZJNk6qaYuDN/Gw68+81kLbkLrc=
+github.com/zoobz-io/capitan v1.0.2/go.mod h1:tFqS6q99gRvgYBzvFIfJMDV1ukWU61H6ZB4HyZmiWuI=
+github.com/zoobz-io/sctx v1.0.3 h1:dkv5F0PWDnjVOPpe+Vr0PwQ5uQrb/zcENSwv4FTR3rw=
+github.com/zoobz-io/sctx v1.0.3/go.mod h1:YH+5vk3FJ+u398Z11rtKlbHW5p9Wl5Bt5WfcvMeZfoQ=
 go.opentelemetry.io/auto/sdk v1.1.0 h1:cH53jehLUN6UFLY71z+NDOiNJqDdPRaXzTel0sJySYA=
 go.opentelemetry.io/auto/sdk v1.1.0/go.mod h1:3wSPjt5PWp2RhlCcmmOial7AvC4DQqZb7a7wCow3W8A=
 go.opentelemetry.io/otel v1.36.0 h1:UumtzIklRBY6cI/lllNZlALOF5nNIzJVb16APdvgTXg=