Batch A: blob storage layer, MCIAS auth, OCI token endpoint

Phase 2 — internal/storage/:
Content-addressed blob storage with atomic writes via rename.
BlobWriter stages data in uploads dir with running SHA-256 hash,
commits by verifying digest then renaming to layers/sha256/<prefix>/<hex>.
Reader provides Open, Stat, Delete, Exists with digest validation.

Phase 3 — internal/auth/ + internal/server/:
MCIAS client with Login and ValidateToken, 30s SHA-256-keyed cache
with lazy eviction and injectable clock for testing. TLS 1.3 minimum
with optional custom CA cert.
Chi router with RequireAuth middleware (Bearer token extraction,
WWW-Authenticate header, OCI error format), token endpoint (Basic
auth → bearer exchange via MCIAS), and /v2/ version check handler.

52 tests passing (14 storage + 9 auth + 9 server + 20 existing).

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

internal/auth/cache.go

@@ -0,0 +1,65 @@
+package auth
+
+import (
+	"sync"
+	"time"
+)
+
+// cacheEntry holds a cached Claims value and its expiration time.
+type cacheEntry struct {
+	claims    *Claims
+	expiresAt time.Time
+}
+
+// validationCache provides a concurrency-safe, TTL-based cache for token
+// validation results. Tokens are keyed by their SHA-256 hex digest.
+type validationCache struct {
+	mu      sync.RWMutex
+	entries map[string]cacheEntry
+	ttl     time.Duration
+	now     func() time.Time // injectable clock for testing
+}
+
+// newCache creates a validationCache with the given TTL.
+func newCache(ttl time.Duration) *validationCache {
+	return &validationCache{
+		entries: make(map[string]cacheEntry),
+		ttl:     ttl,
+		now:     time.Now,
+	}
+}
+
+// get returns cached claims for the given token hash, or false if the
+// entry is missing or expired. Expired entries are lazily evicted.
+func (c *validationCache) get(tokenHash string) (*Claims, bool) {
+	c.mu.RLock()
+	entry, ok := c.entries[tokenHash]
+	c.mu.RUnlock()
+
+	if !ok {
+		return nil, false
+	}
+
+	if c.now().After(entry.expiresAt) {
+		// Lazy evict the expired entry.
+		c.mu.Lock()
+		// Re-check under write lock in case another goroutine already evicted.
+		if e, exists := c.entries[tokenHash]; exists && c.now().After(e.expiresAt) {
+			delete(c.entries, tokenHash)
+		}
+		c.mu.Unlock()
+		return nil, false
+	}
+
+	return entry.claims, true
+}
+
+// put stores claims in the cache with an expiration of now + TTL.
+func (c *validationCache) put(tokenHash string, claims *Claims) {
+	c.mu.Lock()
+	c.entries[tokenHash] = cacheEntry{
+		claims:    claims,
+		expiresAt: c.now().Add(c.ttl),
+	}
+	c.mu.Unlock()
+}

internal/auth/cache_test.go

@@ -0,0 +1,71 @@
+package auth
+
+import (
+	"sync"
+	"testing"
+	"time"
+)
+
+func TestCachePutGet(t *testing.T) {
+	t.Helper()
+	c := newCache(30 * time.Second)
+
+	claims := &Claims{Subject: "alice", AccountType: "user", Roles: []string{"reader"}}
+	c.put("abc123", claims)
+
+	got, ok := c.get("abc123")
+	if !ok {
+		t.Fatal("expected cache hit, got miss")
+	}
+	if got.Subject != "alice" {
+		t.Fatalf("subject: got %q, want %q", got.Subject, "alice")
+	}
+}
+
+func TestCacheTTLExpiry(t *testing.T) {
+	t.Helper()
+	now := time.Now()
+	c := newCache(30 * time.Second)
+	c.now = func() time.Time { return now }
+
+	claims := &Claims{Subject: "bob"}
+	c.put("def456", claims)
+
+	// Still within TTL.
+	got, ok := c.get("def456")
+	if !ok {
+		t.Fatal("expected cache hit before TTL expiry")
+	}
+	if got.Subject != "bob" {
+		t.Fatalf("subject: got %q, want %q", got.Subject, "bob")
+	}
+
+	// Advance clock past TTL.
+	c.now = func() time.Time { return now.Add(31 * time.Second) }
+
+	_, ok = c.get("def456")
+	if ok {
+		t.Fatal("expected cache miss after TTL expiry, got hit")
+	}
+}
+
+func TestCacheConcurrent(t *testing.T) {
+	t.Helper()
+	c := newCache(30 * time.Second)
+
+	var wg sync.WaitGroup
+	for i := range 100 {
+		wg.Add(2)
+		key := string(rune('A' + i%26))
+		go func() {
+			defer wg.Done()
+			c.put(key, &Claims{Subject: key})
+		}()
+		go func() {
+			defer wg.Done()
+			c.get(key) //nolint:gosec // result intentionally ignored in concurrency test
+		}()
+	}
+	wg.Wait()
+	// If we get here without a race detector complaint, the test passes.
+}

internal/auth/claims.go

@@ -0,0 +1,27 @@
+package auth
+
+import "context"
+
+// Claims represents the validated identity and roles extracted from an
+// MCIAS token.
+type Claims struct {
+	Subject     string
+	AccountType string
+	Roles       []string
+}
+
+// claimsKey is an unexported type used as the context key for Claims,
+// preventing collisions with keys from other packages.
+type claimsKey struct{}
+
+// ContextWithClaims returns a new context carrying the given Claims.
+func ContextWithClaims(ctx context.Context, c *Claims) context.Context {
+	return context.WithValue(ctx, claimsKey{}, c)
+}
+
+// ClaimsFromContext extracts Claims from the context. It returns nil if
+// no claims are present.
+func ClaimsFromContext(ctx context.Context) *Claims {
+	c, _ := ctx.Value(claimsKey{}).(*Claims)
+	return c
+}

internal/auth/client.go

@@ -0,0 +1,179 @@
+package auth
+
+import (
+	"bytes"
+	"crypto/sha256"
+	"crypto/tls"
+	"crypto/x509"
+	"encoding/hex"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"os"
+	"strings"
+	"time"
+)
+
+const cacheTTL = 30 * time.Second
+
+// Client communicates with an MCIAS server for authentication and token
+// validation. It caches successful validation results for 30 seconds.
+type Client struct {
+	httpClient  *http.Client
+	baseURL     string
+	serviceName string
+	tags        []string
+	cache       *validationCache
+}
+
+// NewClient creates an auth Client that talks to the MCIAS server at
+// serverURL. If caCert is non-empty, it is loaded as a PEM file and
+// used as the only trusted root CA. TLS 1.3 is required for all HTTPS
+// connections.
+//
+// For plain HTTP URLs (used in tests), TLS configuration is skipped.
+func NewClient(serverURL, caCert, serviceName string, tags []string) (*Client, error) {
+	transport := &http.Transport{}
+
+	if !strings.HasPrefix(serverURL, "http://") {
+		tlsCfg := &tls.Config{
+			MinVersion: tls.VersionTLS13,
+		}
+
+		if caCert != "" {
+			pem, err := os.ReadFile(caCert) //nolint:gosec // CA cert path is operator-supplied
+			if err != nil {
+				return nil, fmt.Errorf("auth: read CA cert %s: %w", caCert, err)
+			}
+			pool := x509.NewCertPool()
+			if !pool.AppendCertsFromPEM(pem) {
+				return nil, fmt.Errorf("auth: no valid certificates in %s", caCert)
+			}
+			tlsCfg.RootCAs = pool
+		}
+
+		transport.TLSClientConfig = tlsCfg
+	}
+
+	return &Client{
+		httpClient: &http.Client{
+			Transport: transport,
+			Timeout:   10 * time.Second,
+		},
+		baseURL:     strings.TrimRight(serverURL, "/"),
+		serviceName: serviceName,
+		tags:        tags,
+		cache:       newCache(cacheTTL),
+	}, nil
+}
+
+// loginRequest is the JSON body sent to MCIAS /v1/auth/login.
+type loginRequest struct {
+	Username    string   `json:"username"`
+	Password    string   `json:"password"`
+	ServiceName string   `json:"service_name"`
+	Tags        []string `json:"tags,omitempty"`
+}
+
+// loginResponse is the JSON body returned by MCIAS /v1/auth/login.
+type loginResponse struct {
+	Token     string `json:"token"`
+	ExpiresIn int    `json:"expires_in"`
+}
+
+// Login authenticates a user against MCIAS and returns a bearer token.
+func (c *Client) Login(username, password string) (token string, expiresIn int, err error) {
+	body, err := json.Marshal(loginRequest{ //nolint:gosec // G117: password is intentionally sent to MCIAS for authentication
+		Username:    username,
+		Password:    password,
+		ServiceName: c.serviceName,
+		Tags:        c.tags,
+	})
+	if err != nil {
+		return "", 0, fmt.Errorf("auth: marshal login request: %w", err)
+	}
+
+	resp, err := c.httpClient.Post(
+		c.baseURL+"/v1/auth/login",
+		"application/json",
+		bytes.NewReader(body),
+	)
+	if err != nil {
+		return "", 0, fmt.Errorf("auth: MCIAS login: %w", ErrMCIASUnavailable)
+	}
+	defer func() { _ = resp.Body.Close() }()
+
+	if resp.StatusCode != http.StatusOK {
+		return "", 0, ErrUnauthorized
+	}
+
+	var lr loginResponse
+	if err := json.NewDecoder(resp.Body).Decode(&lr); err != nil {
+		return "", 0, fmt.Errorf("auth: decode login response: %w", err)
+	}
+
+	return lr.Token, lr.ExpiresIn, nil
+}
+
+// validateRequest is the JSON body sent to MCIAS /v1/token/validate.
+type validateRequest struct {
+	Token string `json:"token"`
+}
+
+// validateResponse is the JSON body returned by MCIAS /v1/token/validate.
+type validateResponse struct {
+	Valid  bool `json:"valid"`
+	Claims struct {
+		Subject     string   `json:"subject"`
+		AccountType string   `json:"account_type"`
+		Roles       []string `json:"roles"`
+	} `json:"claims"`
+}
+
+// ValidateToken checks a bearer token against MCIAS. Results are cached
+// by SHA-256 hash for 30 seconds.
+func (c *Client) ValidateToken(token string) (*Claims, error) {
+	h := sha256.Sum256([]byte(token))
+	tokenHash := hex.EncodeToString(h[:])
+
+	if claims, ok := c.cache.get(tokenHash); ok {
+		return claims, nil
+	}
+
+	body, err := json.Marshal(validateRequest{Token: token})
+	if err != nil {
+		return nil, fmt.Errorf("auth: marshal validate request: %w", err)
+	}
+
+	resp, err := c.httpClient.Post(
+		c.baseURL+"/v1/token/validate",
+		"application/json",
+		bytes.NewReader(body),
+	)
+	if err != nil {
+		return nil, fmt.Errorf("auth: MCIAS validate: %w", ErrMCIASUnavailable)
+	}
+	defer func() { _ = resp.Body.Close() }()
+
+	if resp.StatusCode != http.StatusOK {
+		return nil, ErrUnauthorized
+	}
+
+	var vr validateResponse
+	if err := json.NewDecoder(resp.Body).Decode(&vr); err != nil {
+		return nil, fmt.Errorf("auth: decode validate response: %w", err)
+	}
+
+	if !vr.Valid {
+		return nil, ErrUnauthorized
+	}
+
+	claims := &Claims{
+		Subject:     vr.Claims.Subject,
+		AccountType: vr.Claims.AccountType,
+		Roles:       vr.Claims.Roles,
+	}
+
+	c.cache.put(tokenHash, claims)
+	return claims, nil
+}

internal/auth/client_test.go

@@ -0,0 +1,220 @@
+package auth
+
+import (
+	"encoding/json"
+	"errors"
+	"net/http"
+	"net/http/httptest"
+	"sync/atomic"
+	"testing"
+	"time"
+)
+
+// newTestServer starts an httptest.Server that routes MCIAS endpoints.
+// The handler functions are pluggable per test.
+func newTestServer(t *testing.T, loginHandler, validateHandler http.HandlerFunc) *httptest.Server {
+	t.Helper()
+	mux := http.NewServeMux()
+	if loginHandler != nil {
+		mux.HandleFunc("/v1/auth/login", loginHandler)
+	}
+	if validateHandler != nil {
+		mux.HandleFunc("/v1/token/validate", validateHandler)
+	}
+	srv := httptest.NewServer(mux)
+	t.Cleanup(srv.Close)
+	return srv
+}
+
+func newTestClient(t *testing.T, serverURL string) *Client {
+	t.Helper()
+	c, err := NewClient(serverURL, "", "mcr-test", []string{"env:test"})
+	if err != nil {
+		t.Fatalf("NewClient: %v", err)
+	}
+	return c
+}
+
+func TestLoginSuccess(t *testing.T) {
+	srv := newTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		var req loginRequest
+		if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+			http.Error(w, "bad request", http.StatusBadRequest)
+			return
+		}
+		w.Header().Set("Content-Type", "application/json")
+		_ = json.NewEncoder(w).Encode(loginResponse{
+			Token:     "tok-abc",
+			ExpiresIn: 3600,
+		})
+	}, nil)
+
+	c := newTestClient(t, srv.URL)
+	token, expiresIn, err := c.Login("alice", "secret")
+	if err != nil {
+		t.Fatalf("Login: %v", err)
+	}
+	if token != "tok-abc" {
+		t.Fatalf("token: got %q, want %q", token, "tok-abc")
+	}
+	if expiresIn != 3600 {
+		t.Fatalf("expiresIn: got %d, want %d", expiresIn, 3600)
+	}
+}
+
+func TestLoginFailure(t *testing.T) {
+	srv := newTestServer(t, func(w http.ResponseWriter, _ *http.Request) {
+		w.WriteHeader(http.StatusUnauthorized)
+	}, nil)
+
+	c := newTestClient(t, srv.URL)
+	_, _, err := c.Login("alice", "wrong")
+	if !errors.Is(err, ErrUnauthorized) {
+		t.Fatalf("Login error: got %v, want %v", err, ErrUnauthorized)
+	}
+}
+
+func TestValidateSuccess(t *testing.T) {
+	srv := newTestServer(t, nil, func(w http.ResponseWriter, _ *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		_ = json.NewEncoder(w).Encode(validateResponse{
+			Valid: true,
+			Claims: struct {
+				Subject     string   `json:"subject"`
+				AccountType string   `json:"account_type"`
+				Roles       []string `json:"roles"`
+			}{
+				Subject:     "alice",
+				AccountType: "user",
+				Roles:       []string{"reader", "writer"},
+			},
+		})
+	})
+
+	c := newTestClient(t, srv.URL)
+	claims, err := c.ValidateToken("valid-token-123")
+	if err != nil {
+		t.Fatalf("ValidateToken: %v", err)
+	}
+	if claims.Subject != "alice" {
+		t.Fatalf("subject: got %q, want %q", claims.Subject, "alice")
+	}
+	if claims.AccountType != "user" {
+		t.Fatalf("account_type: got %q, want %q", claims.AccountType, "user")
+	}
+	if len(claims.Roles) != 2 || claims.Roles[0] != "reader" || claims.Roles[1] != "writer" {
+		t.Fatalf("roles: got %v, want [reader writer]", claims.Roles)
+	}
+}
+
+func TestValidateRevoked(t *testing.T) {
+	srv := newTestServer(t, nil, func(w http.ResponseWriter, _ *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		_ = json.NewEncoder(w).Encode(validateResponse{Valid: false})
+	})
+
+	c := newTestClient(t, srv.URL)
+	_, err := c.ValidateToken("revoked-token")
+	if !errors.Is(err, ErrUnauthorized) {
+		t.Fatalf("ValidateToken error: got %v, want %v", err, ErrUnauthorized)
+	}
+}
+
+func TestValidateCacheHit(t *testing.T) {
+	var callCount atomic.Int64
+
+	srv := newTestServer(t, nil, func(w http.ResponseWriter, _ *http.Request) {
+		callCount.Add(1)
+		w.Header().Set("Content-Type", "application/json")
+		_ = json.NewEncoder(w).Encode(validateResponse{
+			Valid: true,
+			Claims: struct {
+				Subject     string   `json:"subject"`
+				AccountType string   `json:"account_type"`
+				Roles       []string `json:"roles"`
+			}{
+				Subject:     "bob",
+				AccountType: "service",
+				Roles:       []string{"admin"},
+			},
+		})
+	})
+
+	c := newTestClient(t, srv.URL)
+
+	// First call — should hit the server.
+	claims1, err := c.ValidateToken("cached-token")
+	if err != nil {
+		t.Fatalf("first ValidateToken: %v", err)
+	}
+	if callCount.Load() != 1 {
+		t.Fatalf("expected 1 server call after first validate, got %d", callCount.Load())
+	}
+
+	// Second call — should come from cache.
+	claims2, err := c.ValidateToken("cached-token")
+	if err != nil {
+		t.Fatalf("second ValidateToken: %v", err)
+	}
+	if callCount.Load() != 1 {
+		t.Fatalf("expected 1 server call after second validate (cache hit), got %d", callCount.Load())
+	}
+
+	if claims1.Subject != claims2.Subject {
+		t.Fatalf("cached claims mismatch: %q vs %q", claims1.Subject, claims2.Subject)
+	}
+}
+
+func TestValidateCacheExpiry(t *testing.T) {
+	var callCount atomic.Int64
+
+	srv := newTestServer(t, nil, func(w http.ResponseWriter, _ *http.Request) {
+		callCount.Add(1)
+		w.Header().Set("Content-Type", "application/json")
+		_ = json.NewEncoder(w).Encode(validateResponse{
+			Valid: true,
+			Claims: struct {
+				Subject     string   `json:"subject"`
+				AccountType string   `json:"account_type"`
+				Roles       []string `json:"roles"`
+			}{
+				Subject:     "charlie",
+				AccountType: "user",
+				Roles:       nil,
+			},
+		})
+	})
+
+	c := newTestClient(t, srv.URL)
+
+	// Inject a controllable clock.
+	now := time.Now()
+	c.cache.now = func() time.Time { return now }
+
+	// First call.
+	if _, err := c.ValidateToken("expiry-token"); err != nil {
+		t.Fatalf("first ValidateToken: %v", err)
+	}
+	if callCount.Load() != 1 {
+		t.Fatalf("expected 1 server call, got %d", callCount.Load())
+	}
+
+	// Second call within TTL — cache hit.
+	if _, err := c.ValidateToken("expiry-token"); err != nil {
+		t.Fatalf("second ValidateToken: %v", err)
+	}
+	if callCount.Load() != 1 {
+		t.Fatalf("expected 1 server call (cache hit), got %d", callCount.Load())
+	}
+
+	// Advance clock past the 30s TTL.
+	c.cache.now = func() time.Time { return now.Add(31 * time.Second) }
+
+	// Third call — cache miss, should hit server again.
+	if _, err := c.ValidateToken("expiry-token"); err != nil {
+		t.Fatalf("third ValidateToken: %v", err)
+	}
+	if callCount.Load() != 2 {
+		t.Fatalf("expected 2 server calls after cache expiry, got %d", callCount.Load())
+	}
+}

internal/auth/errors.go

@@ -0,0 +1,8 @@
+package auth
+
+import "errors"
+
+var (
+	ErrUnauthorized     = errors.New("auth: unauthorized")
+	ErrMCIASUnavailable = errors.New("auth: MCIAS unavailable")
+)