@x47base/pocketbase-addon 0.1.0

package/cmd/loadtest/main.go

@@ -0,0 +1,61 @@
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"flag"
+	"fmt"
+	"github.com/spink-dev/pocketbase-extension/loadtest"
+	"os"
+	"os/signal"
+	"time"
+)
+
+func main() {
+	var c loadtest.Config
+	flag.StringVar(&c.Target, "target", "http://127.0.0.1:8090/api/health", "local disposable PocketBase target")
+	flag.IntVar(&c.Rate, "rate", 20, "total requests per second")
+	flag.IntVar(&c.Clients, "clients", 4, "maximum concurrent clients")
+	flag.DurationVar(&c.Duration, "duration", 10*time.Second, "maximum run duration")
+	flag.IntVar(&c.MaxRequests, "requests", 200, "maximum total requests")
+	sandbox := flag.Bool("sandbox", false, "create a disposable database with 5000 fixture records")
+	mode := flag.String("mode", "observe", "sandbox protection mode: disabled, observe, enforce")
+	dryRun := flag.Bool("dry-run", false, "validate budgets without traffic or database creation")
+	flag.IntVar(&c.NormalEvery, "normal-every", 0, "send a health canary every N scheduled requests, 2..100")
+	flag.Parse()
+	if *mode != "disabled" && *mode != "observe" && *mode != "enforce" {
+		fmt.Fprintln(os.Stderr, "invalid sandbox mode")
+		os.Exit(2)
+	}
+	if *sandbox {
+		c.Target = "http://127.0.0.1:8090/api/collections/pb_sim_records/records"
+	}
+	if err := loadtest.Validate(c); err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(2)
+	}
+	if *dryRun {
+		json.NewEncoder(os.Stdout).Encode(c)
+		return
+	}
+	if *sandbox {
+		target, cleanup, err := startSandbox(*mode)
+		if err != nil {
+			fmt.Fprintln(os.Stderr, err)
+			os.Exit(1)
+		}
+		defer cleanup()
+		c.Target = target
+	}
+	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt)
+	defer stop()
+	report, err := loadtest.Run(ctx, c)
+	if err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+	if err := json.NewEncoder(os.Stdout).Encode(report); err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+}

package/cmd/loadtest/sandbox.go

@@ -0,0 +1,73 @@
+package main
+
+import (
+	"net/http/httptest"
+	"os"
+
+	"github.com/pocketbase/pocketbase/apis"
+	"github.com/pocketbase/pocketbase/core"
+	_ "github.com/pocketbase/pocketbase/migrations"
+	"github.com/pocketbase/pocketbase/tools/types"
+	"github.com/spink-dev/pocketbase-extension/security"
+)
+
+func startSandbox(mode string) (string, func(), error) {
+	config := security.DefaultConfig()
+	config.Mode = mode
+	if err := config.Validate(); err != nil {
+		return "", nil, err
+	}
+	dir, err := os.MkdirTemp("", "pb-simulation-*")
+	if err != nil {
+		return "", nil, err
+	}
+	app := core.NewBaseApp(core.BaseAppConfig{DataDir: dir})
+	cleanup := func() { app.ResetBootstrapState(); os.RemoveAll(dir) }
+	if err := app.Bootstrap(); err != nil {
+		cleanup()
+		return "", nil, err
+	}
+	collection := core.NewBaseCollection("pb_sim_records")
+	collection.ListRule = types.Pointer("")
+	collection.ViewRule = types.Pointer("")
+	collection.Fields.Add(&core.TextField{Name: "label"}, &core.NumberField{Name: "sequence"})
+	if err := app.Save(collection); err != nil {
+		cleanup()
+		return "", nil, err
+	}
+	err = app.RunInTransaction(func(tx core.App) error {
+		for i := 0; i < 5000; i++ {
+			r := core.NewRecord(collection)
+			r.Set("label", "simulation fixture")
+			r.Set("sequence", i)
+			if err := tx.Save(r); err != nil {
+				return err
+			}
+		}
+		return nil
+	})
+	if err != nil {
+		cleanup()
+		return "", nil, err
+	}
+	service, err := security.New(config)
+	if err != nil {
+		cleanup()
+		return "", nil, err
+	}
+	router, err := apis.NewRouter(app)
+	if err != nil {
+		service.Close()
+		cleanup()
+		return "", nil, err
+	}
+	service.Bind(router)
+	handler, err := router.BuildMux()
+	if err != nil {
+		service.Close()
+		cleanup()
+		return "", nil, err
+	}
+	server := httptest.NewServer(handler)
+	return server.URL + "/api/collections/pb_sim_records/records", func() { server.Close(); service.Close(); cleanup() }, nil
+}

package/cmd/loadtest/sandbox_test.go

@@ -0,0 +1,20 @@
+package main
+
+import (
+	"context"
+	"github.com/spink-dev/pocketbase-extension/loadtest"
+	"testing"
+	"time"
+)
+
+func TestSandboxRunsRealDatabase(t *testing.T) {
+	target, cleanup, err := startSandbox("observe")
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer cleanup()
+	report, err := loadtest.Run(context.Background(), loadtest.Config{Target: target, Rate: 10, Clients: 1, Duration: time.Second, MaxRequests: 2, NormalEvery: 2})
+	if err != nil || report.Errors != 0 || report.StatusClasses[2] != 2 || report.CanarySucceeded != 1 {
+		t.Fatalf("sandbox failed: %+v %v", report, err)
+	}
+}

package/cmd/pocketbase/main.go

@@ -0,0 +1,78 @@
+package main
+
+import (
+	"github.com/pocketbase/pocketbase"
+	"github.com/pocketbase/pocketbase/core"
+	"github.com/pocketbase/pocketbase/plugins/migratecmd"
+	adapter "github.com/spink-dev/pocketbase-extension"
+	_ "github.com/spink-dev/pocketbase-extension/features"
+	"github.com/spink-dev/pocketbase-extension/jsvm"
+	"github.com/spink-dev/pocketbase-extension/web"
+	"log"
+	"os"
+	"path/filepath"
+	"strings"
+)
+
+func main() {
+	app := pocketbase.New()
+	var hooksDir, migrationsDir, publicDir, fallback string
+	var watchHooks, automigrate bool
+	app.RootCmd.PersistentFlags().StringVar(&hooksDir, "hooksDir", "", "JS hooks directory (default: sibling of data directory)")
+	app.RootCmd.PersistentFlags().StringVar(&migrationsDir, "migrationsDir", "", "JS migrations directory (default: sibling of data directory)")
+	app.RootCmd.PersistentFlags().BoolVar(&watchHooks, "hooksWatch", false, "Restart on JS hook changes")
+	app.RootCmd.PersistentFlags().BoolVar(&automigrate, "automigrate", true, "Generate JS collection migrations")
+	app.RootCmd.PersistentFlags().StringVar(&publicDir, "publicDir", "./pb_public", "Static files directory")
+	app.RootCmd.PersistentFlags().StringVar(&fallback, "staticFallback", "index.html", "Missing-file fallback; empty disables it")
+	if err := app.RootCmd.ParseFlags(os.Args[1:]); err != nil {
+		log.Fatal(err)
+	}
+	config := adapter.DefaultConfig()
+	statePath, err := filepath.Abs(filepath.Join(app.DataDir(), "security", "state.json"))
+	if err != nil {
+		log.Fatal(err)
+	}
+	config.StatePath = statePath
+	if override := os.Getenv("PB_SECURITY_STATE_PATH"); override != "" {
+		config.StatePath = override
+	}
+	if secretPath := os.Getenv("PB_BACKUP_ENCRYPTION_KEY_FILE"); secretPath != "" {
+		raw, err := os.ReadFile(secretPath)
+		if err != nil {
+			log.Fatal("cannot read backup encryption key file")
+		}
+		key := strings.TrimSuffix(strings.TrimSuffix(string(raw), "\n"), "\r")
+		if len(key) < 32 || len(key) > 1024 {
+			log.Fatal("backup encryption key must contain 32-1024 bytes")
+		}
+		if err := os.Setenv("PB_BACKUP_ENCRYPTION_KEY", key); err != nil {
+			log.Fatal(err)
+		}
+	}
+	if mode := os.Getenv("PB_SECURITY_MODE"); mode != "" {
+		config.Mode = mode
+	}
+	if value := os.Getenv("PB_SECURITY_TRUSTED_PEERS"); value != "" {
+		config.TrustedPeers = strings.Split(value, ",")
+	}
+	if value := os.Getenv("PB_SECURITY_MANAGEMENT_PEERS"); value != "" {
+		config.ManagementPeers = strings.Split(value, ",")
+	}
+	if value := os.Getenv("PB_SECURITY_OPERATOR_PEERS"); value != "" {
+		config.OperatorPeers = strings.Split(value, ",")
+	}
+	if err := adapter.Register(app, config); err != nil {
+		log.Fatal(err)
+	}
+	jsvm.MustRegister(app, jsvm.Config{HooksDir: hooksDir, MigrationsDir: migrationsDir, HooksWatch: watchHooks, HooksPoolSize: 15})
+	migratecmd.MustRegister(app, app.RootCmd, migratecmd.Config{Dir: migrationsDir, Automigrate: automigrate, TemplateLang: migratecmd.TemplateLangJS})
+	app.OnServe().BindFunc(func(e *core.ServeEvent) error {
+		if !e.Router.HasRoute("GET", "/{path...}") {
+			e.Router.GET("/{path...}", web.StaticWithOptions(os.DirFS(publicDir), web.StaticOptions{Fallback: fallback}))
+		}
+		return e.Next()
+	})
+	if err := app.Start(); err != nil {
+		log.Fatal(err)
+	}
+}

package/deploy/README.md

@@ -0,0 +1,148 @@
+# Edge-protected PocketBase
+
+Two containers: the public gateway rejects traffic before PocketBase; the database
+has no published port. Use this as a single-host deployment template, with upstream
+TLS/DDoS protection appropriate to your hosting provider.
+
+```sh
+cd /Users/x47base/git/spink-dev_pocketbase-extension
+docker compose -f deploy/compose.yaml up --build -d --wait
+docker compose -f deploy/compose.yaml logs pocketbase
+```
+
+Complete the first-run superuser setup link through **http://127.0.0.1:8081/_/**
+(replace the origin in the container's printed link with that address). There are
+no default credentials. This creates a **new database** in named Docker volumes;
+your existing development instance on 8090 and its admin account are untouched.
+
+| Address | Purpose |
+|---|---|
+| `http://127.0.0.1:8080` | Public API: explicitly allowed collections only |
+| `http://127.0.0.1:8081/_/` | Native admin, Security, Backups, x47base extensions |
+| `http://127.0.0.1:8081/edge/status` | Gateway accepted/rejected counts, active work, readiness |
+| `http://127.0.0.1:8081/edge/healthz` | Gateway process liveness; no database call |
+| `http://127.0.0.1:8081/edge/readyz` | Policy validity plus cached upstream health |
+
+The operator port is loopback-only and keeps native PocketBase authentication.
+Use an SSH tunnel for remote administration. Do not publish port 8081 publicly;
+its diagnostics are intentionally local, without a second login mechanism.
+
+```mermaid
+flowchart LR
+    Internet[Public client] --> Edge[Gateway checks and budgets]
+    Edge --> DB[Private PocketBase]
+    Operator[Local admin or SSH tunnel] --> Lane[Reserved operator lane]
+    Lane --> DB
+    DB --> State[Security checkpoint volume]
+    State -. read only, one second poll .-> Edge
+    App[Versioned migrations and hooks] --> DB
+```
+
+## Ship your schema and application
+
+1. Replace `deploy/app/migrations/1789000000_notes.js` **before first deployment**
+   with reviewed PocketBase JS migrations defining your collections, rules and
+   indexes. The example creates private `notes` with title/body fields. Native
+   migration history applies each version once. Add new migrations for subsequent
+   changes; do not edit already-applied versions.
+2. Place trusted JS hooks in `deploy/app/hooks` and static assets in
+   `deploy/app/public`. These are baked into the image, with no writable hooks or
+   automatic migration generation in production. Static assets are operator-only
+   under the default public allowlist; host the public frontend separately.
+3. List the permitted collection names (and IDs if clients use IDs) in
+   `deploy/edge.json` → `collections`. This grants network reachability only;
+   native collection rules still control data access. Add auth collections too.
+4. Rebuild and deploy. Review migrations against a disposable restored copy first.
+   Do not run two PocketBase containers against one data volume. Take a backup
+   before a schema upgrade; rollback may require the old binary and database copy.
+
+## Pre-database protection
+
+`deploy/edge.json` is read every second. Use `blockedCIDRs` for IP/CIDR blocks and
+`blockedPaths` for literal path-prefix blocks. Malformed policy or a missing,
+invalid, or older-than-30-seconds security checkpoint denies public traffic with
+503. Correcting the file automatically recovers. When replacing bind-mounted
+files atomically, recreate the edge container so Docker mounts the new inode:
+`docker compose -f deploy/compose.yaml up -d --force-recreate edge`.
+
+Temporary family blocks made in **Security → Protection** are enforced at the
+edge from the last successfully persisted checkpoint, within approximately one
+second. They apply in **enforce** mode and expire at their configured time. Requests
+already admitted are not recalled. If checkpoint writes fail, the old policy can
+remain active for up to 30 seconds before public access fails closed. Admin access
+remains available to diagnose and recover. Preserve the separate security volume
+when replacing the database; it is not included in database backup archives.
+
+Defaults: 50 public requests/second (burst 100), 20 per client (burst 40), 32 active
+requests, 1MiB bodies, 4096 tracked clients. No waiting queue is added. New identities
+are denied when the bounded table is full; idle entries expire after a minute.
+Public bodies, including chunked bodies, are read and size-checked **before** any
+upstream side effect. Aggregate configured body buffering is capped at 128MiB.
+Public connections cap at 256, headers at 16KiB, header reads at 3 seconds, request
+reads at 10 seconds, writes at 30 seconds. Realtime streams must reconnect after
+the public write deadline; they share the public concurrency budget.
+
+The gateway denies public admin/settings/backups/schema/batch routes, ambiguous
+encoded paths, unknown collections and all unlisted custom routes. Public file
+access is limited to allowed collections; native authorization still runs. The
+separate `/api/files/token` endpoint is not exposed by this template. Deployments
+using batch, custom routes, large uploads or longer streams need reviewed gateway
+changes/limits; there is no catch-all proxy bypass.
+
+The runtime-only `PB_SECURITY_OPERATOR_PEERS` list opts the private gateway into
+PocketBase's bounded management lane using `X-Spink-Operator`. Public requests have
+that marker stripped. Native authentication/authorization still run, including for
+operator requests. Do not enable this on a proxy that forwards user-supplied markers.
+The setting is deliberately absent from editable/persisted policy JSON.
+
+Client-supplied forwarding headers are replaced. `trustedProxies` is empty by
+default. When putting a TLS proxy in front, restrict the public port at the host
+firewall to that proxy and list only its actual CIDRs; it must sanitize incoming
+forwarding headers. Never trust all addresses. Docker Desktop may present a shared
+host IP, so inspect your production network before relying on per-client limits.
+PocketBase trusts only the gateway's fixed private IP. If changing the subnet,
+change both Compose IPs and the PocketBase peer environment variables. On an
+existing database, review persisted Security policy peer lists as well.
+
+## Deployment boundaries and secrets
+
+Containers run non-root, with read-only roots, dropped capabilities, resource and
+log limits. The backend network is internal. It has **no external SMTP/S3/OAuth
+provider access by default**; add a controlled egress network/firewall if needed.
+Do not remove the private network or publish the database port to fix egress.
+The default public bind is also loopback. Exposing it uses `PB_PUBLIC_BIND` and
+requires an external TLS/network edge; this template itself serves HTTP.
+
+Optional encrypted-backup key via a mounted Docker secret:
+
+```sh
+export PB_BACKUP_KEY_FILE=/absolute/protected/backup-key
+# File contains an independently generated 32–1024 byte secret, retained offline.
+docker compose -f deploy/compose.yaml -f deploy/compose.secrets.yaml up -d --build
+```
+
+Then enable encryption in Settings → x47base extensions. The default key environment
+name remains `PB_BACKUP_ENCRYPTION_KEY`. Do not commit keys or put them in images.
+Docker Compose secret files still require secure host storage. Custom images
+should pin approved base-image digests and pass your image scanning policy.
+
+Health checks report health; Docker restart policy restarts exited processes,
+not merely unhealthy ones. Rejection reduces database work; it cannot guarantee
+availability during link saturation, host exhaustion, disk failure or costly
+allowed queries. Use provider/CDN DDoS protection, backups and external monitoring.
+Gateway rejections appear in `/edge/status`; PocketBase incidents only describe
+traffic that reaches PocketBase, so the two counts intentionally differ.
+
+## Verification and stopping
+
+```sh
+go test -race ./edge
+# Bounded local smoke; repeated blocked admin paths never reach PocketBase:
+python3 scripts/check-edge.py --public http://127.0.0.1:8080 --operator http://127.0.0.1:8081
+# Stop without deleting data:
+docker compose -f deploy/compose.yaml down
+```
+
+`down -v` deletes database and security volumes; do not use it for a real deployment.
+Compose behavior follows the [official services](https://docs.docker.com/reference/compose-file/services/)
+and [network documentation](https://docs.docker.com/reference/compose-file/networks/).

package/deploy/app/hooks/README.md

@@ -0,0 +1,2 @@
+Place trusted application *.pb.js hooks here. Rebuild the image to deploy changes.
+Hooks execute server-side code with database access; only ship reviewed code.

package/deploy/app/migrations/1789000000_notes.js

@@ -0,0 +1,16 @@
+// Example schema: private until application-specific record rules are added.
+migrate((app) => {
+    const collection = new Collection({
+        name: "notes",
+        type: "base",
+        fields: [
+            { name: "title", type: "text", required: true, max: 200 },
+            { name: "body", type: "text", max: 10000 }
+        ],
+        listRule: null, viewRule: null, createRule: null,
+        updateRule: null, deleteRule: null
+    });
+    app.save(collection);
+}, (app) => {
+    app.delete(app.findCollectionByNameOrId("notes"));
+});

package/deploy/app/public/README.md

@@ -0,0 +1,2 @@
+Place application static assets here. They are available through the operator
+listener only by default. The public gateway exposes allowed API routes only.

package/deploy/compose.secrets.yaml

@@ -0,0 +1,8 @@
+services:
+  pocketbase:
+    environment:
+      PB_BACKUP_ENCRYPTION_KEY_FILE: /run/secrets/backup_key
+    secrets: [backup_key]
+secrets:
+  backup_key:
+    file: ${PB_BACKUP_KEY_FILE:?Set PB_BACKUP_KEY_FILE to your protected key file}

package/deploy/compose.yaml

@@ -0,0 +1,68 @@
+name: spink-pocketbase
+services:
+  pocketbase:
+    build:
+      context: ..
+      target: pocketbase
+    image: spink-pocketbase:local
+    restart: unless-stopped
+    read_only: true
+    cap_drop: [ALL]
+    security_opt: [no-new-privileges:true]
+    pids_limit: 128
+    mem_limit: 512m
+    cpus: 1.5
+    tmpfs: ["/tmp:size=64m,mode=1777"]
+    environment:
+      PB_SECURITY_MODE: enforce
+      PB_SECURITY_STATE_PATH: /state/state.json
+      PB_SECURITY_OPERATOR_PEERS: 172.30.80.2/32
+      PB_SECURITY_TRUSTED_PEERS: 172.30.80.2/32
+      PB_SECURITY_MANAGEMENT_PEERS: 172.30.80.2/32,127.0.0.0/8,::1/128
+      GOMEMLIMIT: 400MiB
+    volumes:
+      - data:/pb_data
+      - security:/state
+    networks:
+      backend:
+        ipv4_address: 172.30.80.3
+    logging: &logs
+      driver: json-file
+      options: {max-size: 10m, max-file: "3"}
+  edge:
+    build:
+      context: ..
+      target: edge
+    image: spink-pocketbase-edge:local
+    restart: unless-stopped
+    read_only: true
+    cap_drop: [ALL]
+    security_opt: [no-new-privileges:true]
+    pids_limit: 128
+    mem_limit: 256m
+    cpus: 1.0
+    environment: {GOMEMLIMIT: 200MiB}
+    ports:
+      - "${PB_PUBLIC_BIND:-127.0.0.1}:${PB_PUBLIC_PORT:-8080}:8080"
+      - "127.0.0.1:${PB_OPERATOR_PORT:-8081}:8081"
+    volumes:
+      - ./edge.json:/etc/spink/edge.json:ro
+      - security:/state:ro
+    depends_on:
+      pocketbase:
+        condition: service_healthy
+    networks:
+      frontend: {}
+      backend:
+        ipv4_address: 172.30.80.2
+    logging: *logs
+networks:
+  frontend: {}
+  backend:
+    internal: true
+    ipam:
+      config:
+        - subnet: 172.30.80.0/24
+volumes:
+  data: {}
+  security: {}

package/deploy/edge.json

@@ -0,0 +1,13 @@
+{
+  "collections": ["notes"],
+  "blockedCIDRs": [],
+  "blockedPaths": [],
+  "trustedProxies": [],
+  "rate": 50,
+  "burst": 100,
+  "clientRate": 20,
+  "clientBurst": 40,
+  "maxClients": 4096,
+  "maxConcurrent": 32,
+  "maxBodyBytes": 1048576
+}