@x47base/pocketbase-addon 0.1.0 → 0.2.0

package/edge/openapi.json

@@ -1 +1,226 @@
-{"openapi":"3.1.0","info":{"title":"Spink edge local diagnostics","version":"0.1.0"},"servers":[{"url":"http://127.0.0.1:8081"}],"paths":{"/edge/healthz":{"get":{"summary":"Gateway process liveness","responses":{"204":{"description":"Alive"}}}},"/edge/readyz":{"get":{"summary":"Validated policy and cached upstream health","responses":{"204":{"description":"Ready"},"503":{"description":"Not ready"}}}},"/edge/status":{"get":{"summary":"Local-only aggregate counters; no database credentials","responses":{"200":{"description":"Status","content":{"application/json":{"schema":{"type":"object","properties":{"policyReady":{"type":"boolean"},"upstreamHealthy":{"type":"boolean"},"active":{"type":"integer"},"trackedClients":{"type":"integer"},"accepted":{"type":"integer"},"rejected":{"type":"integer"}}}}}}}}}}}
+{
+  "openapi": "3.1.0",
+  "info": {
+    "title": "Spink edge local diagnostics",
+    "version": "0.1.0"
+  },
+  "servers": [
+    {
+      "url": "http://127.0.0.1:8081"
+    }
+  ],
+  "paths": {
+    "/edge/healthz": {
+      "get": {
+        "summary": "Gateway process liveness",
+        "responses": {
+          "204": {
+            "description": "Alive"
+          }
+        }
+      }
+    },
+    "/edge/readyz": {
+      "get": {
+        "summary": "Validated policy and cached upstream health",
+        "responses": {
+          "204": {
+            "description": "Ready"
+          },
+          "503": {
+            "description": "Not ready"
+          }
+        }
+      }
+    },
+    "/edge/status": {
+      "get": {
+        "summary": "Local-only aggregate counters; no database credentials",
+        "responses": {
+          "200": {
+            "description": "Status",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "version": {
+                      "type": "integer"
+                    },
+                    "active": {
+                      "type": "integer"
+                    },
+                    "trackedClients": {
+                      "type": "integer"
+                    },
+                    "requests": {
+                      "type": "integer"
+                    },
+                    "forwarded": {
+                      "type": "integer"
+                    },
+                    "accepted": {
+                      "type": "integer"
+                    },
+                    "rejected": {
+                      "type": "integer"
+                    },
+                    "bodyReadBytes": {
+                      "type": "integer"
+                    },
+                    "declaredRejectedBytes": {
+                      "type": "integer"
+                    },
+                    "upstreamFailures": {
+                      "type": "integer"
+                    },
+                    "maxBodyBytes": {
+                      "type": "integer"
+                    },
+                    "bodyReadTimeoutSeconds": {
+                      "type": "integer"
+                    },
+                    "maxConcurrent": {
+                      "type": "integer"
+                    },
+                    "maxClientConcurrent": {
+                      "type": "integer"
+                    },
+                    "session": {
+                      "type": "string"
+                    },
+                    "startedAt": {
+                      "type": "string",
+                      "format": "date-time"
+                    },
+                    "updatedAt": {
+                      "type": "string",
+                      "format": "date-time"
+                    },
+                    "policyReady": {
+                      "type": "boolean"
+                    },
+                    "upstreamHealthy": {
+                      "type": "boolean"
+                    },
+                    "reasons": {
+                      "type": "object",
+                      "additionalProperties": {
+                        "type": "integer"
+                      }
+                    },
+                    "traffic": {
+                      "type": "array",
+                      "maxItems": 60,
+                      "items": {
+                        "type": "object",
+                        "properties": {
+                          "at": {
+                            "type": "string",
+                            "format": "date-time"
+                          },
+                          "seconds": {
+                            "type": "number"
+                          },
+                          "count": {
+                            "type": "integer"
+                          },
+                          "rejected": {
+                            "type": "integer"
+                          },
+                          "failures": {
+                            "type": "integer"
+                          },
+                          "slow": {
+                            "type": "integer"
+                          }
+                        }
+                      }
+                    },
+                    "incidents": {
+                      "type": "array",
+                      "maxItems": 128,
+                      "items": {
+                        "type": "object",
+                        "properties": {
+                          "id": {
+                            "type": "integer"
+                          },
+                          "source": {
+                            "type": "string",
+                            "enum": [
+                              "edge",
+                              "pocketbase"
+                            ]
+                          },
+                          "sourceId": {
+                            "type": "string"
+                          },
+                          "reason": {
+                            "type": "string"
+                          },
+                          "severity": {
+                            "type": "string",
+                            "enum": [
+                              "notice",
+                              "warning"
+                            ]
+                          },
+                          "family": {
+                            "type": "string"
+                          },
+                          "phase": {
+                            "type": "string",
+                            "enum": [
+                              "active",
+                              "recovering",
+                              "resolved"
+                            ]
+                          },
+                          "firstSeen": {
+                            "type": "string",
+                            "format": "date-time"
+                          },
+                          "lastSeen": {
+                            "type": "string",
+                            "format": "date-time"
+                          },
+                          "acknowledged": {
+                            "type": "boolean"
+                          },
+                          "evidence": {
+                            "type": "object",
+                            "properties": {
+                              "count": {
+                                "type": "integer"
+                              },
+                              "rejected": {
+                                "type": "integer"
+                              },
+                              "failures": {
+                                "type": "integer"
+                              },
+                              "slow": {
+                                "type": "integer"
+                              },
+                              "bodyReadBytes": {
+                                "type": "integer"
+                              },
+                              "declaredRejectedBytes": {
+                                "type": "integer"
+                              }
+                            }
+                          }
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/edge/policy.go

@@ -14,21 +14,32 @@ import (
 )
 
 type Policy struct {
-	Collections      []string `json:"collections"`
-	BlockedCIDRs     []string `json:"blockedCIDRs"`
-	BlockedPaths     []string `json:"blockedPaths"`
-	TrustedProxies   []string `json:"trustedProxies"`
-	Rate             int      `json:"rate"`
-	Burst            int      `json:"burst"`
-	ClientRate       int      `json:"clientRate"`
-	ClientBurst      int      `json:"clientBurst"`
-	MaxClients       int      `json:"maxClients"`
-	MaxConcurrent    int      `json:"maxConcurrent"`
-	MaxBodyBytes     int64    `json:"maxBodyBytes"`
-	blocked, trusted []netip.Prefix
+	Collections            []string `json:"collections"`
+	BlockedCIDRs           []string `json:"blockedCIDRs"`
+	BlockedPaths           []string `json:"blockedPaths"`
+	TrustedProxies         []string `json:"trustedProxies"`
+	Rate                   int      `json:"rate"`
+	Burst                  int      `json:"burst"`
+	ClientRate             int      `json:"clientRate"`
+	ClientBurst            int      `json:"clientBurst"`
+	MaxClients             int      `json:"maxClients"`
+	MaxConcurrent          int      `json:"maxConcurrent"`
+	MaxClientConcurrent    int      `json:"maxClientConcurrent"`
+	BodyReadTimeoutSeconds int      `json:"bodyReadTimeoutSeconds"`
+	MaxBodyBytes           int64    `json:"maxBodyBytes"`
+	blocked, trusted       []netip.Prefix
 }
 
 func (p *Policy) Validate() error {
+	if p.MaxClientConcurrent == 0 {
+		p.MaxClientConcurrent = min(4, p.MaxConcurrent)
+	}
+	if p.BodyReadTimeoutSeconds == 0 {
+		p.BodyReadTimeoutSeconds = 5
+	}
+	if p.MaxClientConcurrent < 1 || p.MaxClientConcurrent > p.MaxConcurrent || p.BodyReadTimeoutSeconds < 1 || p.BodyReadTimeoutSeconds > 10 {
+		return errors.New("invalid per-client concurrency or body timeout")
+	}
 	if p.Rate < 1 || p.Rate > 100000 || p.Burst < 1 || p.Burst > 100000 || p.ClientRate < 1 || p.ClientRate > 10000 || p.ClientBurst < 1 || p.ClientBurst > 10000 || p.MaxClients < 1 || p.MaxClients > 100000 || p.MaxConcurrent < 1 || p.MaxConcurrent > 1024 || p.MaxBodyBytes < 1 || p.MaxBodyBytes > 32<<20 {
 		return errors.New("invalid edge limits")
 	}

package/edge/telemetry.go

@@ -0,0 +1,187 @@
+package edge
+
+import (
+	"crypto/rand"
+	"encoding/hex"
+	"encoding/json"
+	"maps"
+	"os"
+	"path/filepath"
+	"strconv"
+	"sync"
+	"time"
+
+	"github.com/spink-dev/pocketbase-extension/security"
+)
+
+type rejectionBucket struct {
+	second int64
+	count  int
+}
+
+type telemetry struct {
+	recent   map[string]*[10]rejectionBucket
+	mu       sync.Mutex
+	state    security.EdgeTelemetry
+	sequence uint64
+}
+
+func newTelemetry() (*telemetry, error) {
+	var id [16]byte
+	if _, err := rand.Read(id[:]); err != nil {
+		return nil, err
+	}
+	return &telemetry{recent: map[string]*[10]rejectionBucket{}, state: security.EdgeTelemetry{Version: 1, Session: hex.EncodeToString(id[:]), StartedAt: time.Now(), Reasons: map[string]uint64{}}}, nil
+}
+func (t *telemetry) window(now time.Time) *security.TrafficWindow {
+	at := now.Truncate(time.Second)
+	if len(t.state.Traffic) == 0 || !t.state.Traffic[len(t.state.Traffic)-1].At.Equal(at) {
+		t.state.Traffic = append(t.state.Traffic, security.TrafficWindow{At: at, Seconds: 1})
+	}
+	cut := 0
+	for cut < len(t.state.Traffic) && t.state.Traffic[cut].At.Before(at.Add(-59*time.Second)) {
+		cut++
+	}
+	if cut > 0 {
+		t.state.Traffic = append([]security.TrafficWindow(nil), t.state.Traffic[cut:]...)
+	}
+	return &t.state.Traffic[len(t.state.Traffic)-1]
+}
+func (t *telemetry) begin() {
+	t.mu.Lock()
+	defer t.mu.Unlock()
+	t.state.Requests++
+	t.window(time.Now()).Count++
+}
+func (t *telemetry) outcome(reason string, read uint64, declared int64) {
+	t.mu.Lock()
+	defer t.mu.Unlock()
+	now := time.Now()
+	t.state.BodyReadBytes += read
+	if reason == "" {
+		t.state.Forwarded++
+		return
+	}
+	t.state.Rejected++
+	t.state.Reasons[reason]++
+	t.window(now).Rejected++
+	claimed := uint64(max(0, declared))
+	t.state.DeclaredRejectedBytes = saturatedAdd(t.state.DeclaredRejectedBytes, claimed)
+	idx := -1
+	for i := len(t.state.Incidents) - 1; i >= 0; i-- {
+		event := t.state.Incidents[i]
+		if event.Reason == reason && now.Sub(event.LastSeen) < time.Minute {
+			idx = i
+			break
+		}
+	}
+	if idx < 0 {
+		t.sequence++
+		t.state.Incidents = append(t.state.Incidents, security.Incident{ID: t.sequence, Source: "edge", SourceID: strconv.FormatUint(t.sequence, 10), Family: "other", Reason: reason, Severity: "notice", FirstSeen: now})
+		if len(t.state.Incidents) > 128 {
+			t.state.Incidents = t.state.Incidents[1:]
+		}
+		idx = len(t.state.Incidents) - 1
+	}
+	event := &t.state.Incidents[idx]
+	event.LastSeen = now
+	event.Phase = "active"
+	event.Evidence.Family = "other"
+	event.Evidence.Count++
+	event.Evidence.Rejected++
+	event.Evidence.BodyReadBytes += read
+	event.Evidence.DeclaredRejectedBytes = saturatedAdd(event.Evidence.DeclaredRejectedBytes, claimed)
+	// Every denial is retained immediately. Severity describes evidence, not attacker intent.
+	if reason == "body_too_large" || reason == "body_timeout" {
+		event.Severity = "warning"
+	}
+	window := t.recent[reason]
+	if window == nil {
+		window = new([10]rejectionBucket)
+		t.recent[reason] = window
+	}
+	second := now.Unix()
+	slot := &window[second%10]
+	if slot.second != second {
+		*slot = rejectionBucket{second: second}
+	}
+	slot.count++
+	recent := 0
+	for _, bucket := range window {
+		if second-bucket.second < 10 {
+			recent += bucket.count
+		}
+	}
+	if recent >= 20 {
+		event.Severity = "warning"
+	}
+}
+func (t *telemetry) upstreamFailure() {
+	t.mu.Lock()
+	defer t.mu.Unlock()
+	t.state.UpstreamFailures++
+	t.window(time.Now()).Failures++
+}
+func (g *Gateway) Telemetry() security.EdgeTelemetry {
+	g.metrics.mu.Lock()
+	now := time.Now()
+	g.metrics.window(now)
+	v := g.metrics.state
+	v.UpdatedAt = now
+	v.Accepted = v.Forwarded
+	v.Reasons = maps.Clone(v.Reasons)
+	v.Traffic = append([]security.TrafficWindow{}, v.Traffic...)
+	v.Incidents = append([]security.Incident{}, v.Incidents...)
+	for i := range v.Incidents {
+		quiet := now.Sub(v.Incidents[i].LastSeen)
+		if quiet >= time.Minute {
+			v.Incidents[i].Phase = "resolved"
+		} else if quiet >= 5*time.Second {
+			v.Incidents[i].Phase = "recovering"
+		}
+	}
+	g.metrics.mu.Unlock()
+	g.mu.Lock()
+	v.PolicyReady = g.valid
+	v.Active = g.active
+	v.TrackedClients = len(g.clients)
+	v.MaxBodyBytes = g.policy.MaxBodyBytes
+	v.BodyReadTimeoutSeconds = g.policy.BodyReadTimeoutSeconds
+	v.MaxConcurrent = g.policy.MaxConcurrent
+	v.MaxClientConcurrent = g.policy.MaxClientConcurrent
+	g.mu.Unlock()
+	v.UpstreamHealthy = g.upstreamHealthy.Load()
+	return v
+}
+
+// WriteTelemetry publishes once per second, never once per rejected request.
+// The telemetry volume is writable only by the edge; policy remains read-only.
+func (g *Gateway) WriteTelemetry(path string) error {
+	raw, err := json.Marshal(g.Telemetry())
+	if err != nil {
+		return err
+	}
+	if err = os.MkdirAll(filepath.Dir(path), 0700); err != nil {
+		return err
+	}
+	f, err := os.CreateTemp(filepath.Dir(path), ".edge-*")
+	if err != nil {
+		return err
+	}
+	defer os.Remove(f.Name())
+	if _, err = f.Write(raw); err != nil {
+		f.Close()
+		return err
+	}
+	if err = f.Close(); err != nil {
+		return err
+	}
+	return os.Rename(f.Name(), path)
+}
+
+func saturatedAdd(a, b uint64) uint64 {
+	if ^uint64(0)-a < b {
+		return ^uint64(0)
+	}
+	return a + b
+}

package/edge/telemetry_test.go

@@ -0,0 +1,181 @@
+package edge
+
+import (
+	"bufio"
+	"fmt"
+	"io"
+	"net"
+	"net/http"
+	"net/http/httptest"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/spink-dev/pocketbase-extension/security"
+)
+
+type unreadBody struct{}
+
+func (unreadBody) Read([]byte) (int, error) { panic("oversized body must not be read") }
+func (unreadBody) Close() error             { return nil }
+
+func TestOversizeBurstIsVisibleWithoutReadingOrForwarding(t *testing.T) {
+	g, n := fixture(t, policy(), nil)
+	for i := 0; i < 25; i++ {
+		r := req("/api/collections/notes/records")
+		r.Method = "POST"
+		r.ContentLength = 1 << 30
+		r.Body = unreadBody{}
+		w := httptest.NewRecorder()
+		g.Public(w, r)
+		if w.Code != 413 {
+			t.Fatal(w.Code)
+		}
+	}
+	v := g.Telemetry()
+	if n.Load() != 0 || v.Requests != 25 || v.Rejected != 25 || v.Forwarded != 0 || v.BodyReadBytes != 0 || v.DeclaredRejectedBytes != 25<<30 || v.Reasons["body_too_large"] != 25 {
+		t.Fatalf("wrong counters: %+v", v)
+	}
+	if len(v.Incidents) != 1 || v.Incidents[0].Evidence.Count != 25 || v.Incidents[0].Severity != "warning" {
+		t.Fatalf("missing burst: %+v", v.Incidents)
+	}
+	file := filepath.Join(t.TempDir(), "edge.json")
+	if err := g.WriteTelemetry(file); err != nil {
+		t.Fatal(err)
+	}
+	imported, err := security.ReadEdgeTelemetry(file, time.Now())
+	if err != nil || imported.Rejected != 25 {
+		t.Fatal(imported, err)
+	}
+	if _, err = security.ReadEdgeTelemetry(file, time.Now().Add(6*time.Second)); err == nil {
+		t.Fatal("stale data accepted")
+	}
+}
+func TestChunkedBodyBoundAndCounters(t *testing.T) {
+	g, n := fixture(t, policy(), nil)
+	r := req("/api/collections/notes/records")
+	r.Method = "POST"
+	r.ContentLength = -1
+	r.Body = io.NopCloser(strings.NewReader(strings.Repeat("x", 2048)))
+	w := httptest.NewRecorder()
+	g.Public(w, r)
+	v := g.Telemetry()
+	if w.Code != 413 || n.Load() != 0 || v.BodyReadBytes != 1025 || v.DeclaredRejectedBytes != 0 {
+		t.Fatalf("code %d telemetry %+v", w.Code, v)
+	}
+}
+func TestSlowBodyAndImmediateLargeHeaderRejection(t *testing.T) {
+	p := policy()
+	p.BodyReadTimeoutSeconds = 1
+	g, n := fixture(t, p, nil)
+	server := httptest.NewServer(http.HandlerFunc(g.Public))
+	defer server.Close()
+	for _, size := range []int64{1 << 30, 100} {
+		conn, err := net.Dial("tcp", strings.TrimPrefix(server.URL, "http://"))
+		if err != nil {
+			t.Fatal(err)
+		}
+		conn.SetDeadline(time.Now().Add(3 * time.Second))
+		start := time.Now()
+		fmt.Fprintf(conn, "POST /api/collections/notes/records HTTP/1.1\r\nHost: test\r\nContent-Length: %d\r\n\r\n", size)
+		response, err := http.ReadResponse(bufio.NewReader(conn), nil)
+		if err != nil {
+			conn.Close()
+			t.Fatal(err)
+		}
+		want := 408
+		if size > 1024 {
+			want = 413
+			if time.Since(start) > 500*time.Millisecond {
+				t.Error("large request waited for body")
+			}
+		}
+		if response.StatusCode != want {
+			t.Errorf("got %d want %d", response.StatusCode, want)
+		}
+		response.Body.Close()
+		conn.Close()
+	}
+	v := g.Telemetry()
+	if n.Load() != 0 || v.Reasons["body_timeout"] != 1 || v.Reasons["body_too_large"] != 1 {
+		t.Fatal(v)
+	}
+}
+func TestClientConcurrencyPreservesOtherClientCapacity(t *testing.T) {
+	entered := make(chan struct{}, 1)
+	release := make(chan struct{})
+	p := policy()
+	p.MaxClientConcurrent = 1
+	g, _ := fixture(t, p, func(w http.ResponseWriter, r *http.Request) {
+		if r.Header.Get("Hold") == "1" {
+			entered <- struct{}{}
+			<-release
+		}
+		w.WriteHeader(204)
+	})
+	done := make(chan struct{})
+	go func() {
+		defer close(done)
+		r := req("/api/health")
+		r.Header.Set("Hold", "1")
+		g.Public(httptest.NewRecorder(), r)
+	}()
+	<-entered
+	w := httptest.NewRecorder()
+	g.Public(w, req("/api/health"))
+	if w.Code != 429 {
+		t.Error(w.Code)
+	}
+	other := req("/api/health")
+	other.RemoteAddr = "198.51.100.2:1234"
+	w = httptest.NewRecorder()
+	g.Public(w, other)
+	if w.Code != 204 {
+		t.Error(w.Code)
+	}
+	close(release)
+	<-done
+	if g.Telemetry().Reasons["client_concurrency"] != 1 {
+		t.Fatal(g.Telemetry())
+	}
+}
+func TestEveryDenialRetainedAndOperatorExcluded(t *testing.T) {
+	g, _ := fixture(t, policy(), nil)
+	for i := 0; i < 40; i++ {
+		g.Public(httptest.NewRecorder(), req("/_/"))
+	}
+	g.Operator(httptest.NewRecorder(), req("/edge/status"))
+	v := g.Telemetry()
+	if v.Requests != 40 || v.Reasons["private_route"] != 40 || v.Incidents[0].Evidence.Count != 40 {
+		t.Fatal(v)
+	}
+	g.metrics.mu.Lock()
+	g.metrics.state.Incidents[0].LastSeen = time.Now().Add(-time.Minute)
+	g.metrics.mu.Unlock()
+	if g.Telemetry().Incidents[0].Phase != "resolved" {
+		t.Fatal("event not resolved after quiet period")
+	}
+}
+
+func TestTruncatedChunkedUploadNeverReachesUpstream(t *testing.T) {
+	g, n := fixture(t, policy(), nil)
+	server := httptest.NewServer(http.HandlerFunc(g.Public))
+	defer server.Close()
+	conn, err := net.Dial("tcp", strings.TrimPrefix(server.URL, "http://"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer conn.Close()
+	conn.SetDeadline(time.Now().Add(3 * time.Second))
+	fmt.Fprint(conn, "POST /api/collections/notes/records HTTP/1.1\r\nHost: test\r\nTransfer-Encoding: chunked\r\n\r\n64\r\nshort")
+	conn.(*net.TCPConn).CloseWrite()
+	response, err := http.ReadResponse(bufio.NewReader(conn), nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer response.Body.Close()
+	if response.StatusCode != 400 || n.Load() != 0 || g.Telemetry().Reasons["body_read_error"] != 1 {
+		t.Fatal(response.StatusCode, n.Load(), g.Telemetry())
+	}
+}