@x47base/pocketbase-addon 0.1.0

package/.dockerignore

@@ -0,0 +1,9 @@
+.git
+pb_data
+*.log
+node_modules
+
+_build
+artifacts
+.env*
+deploy/secrets

package/Dockerfile

@@ -0,0 +1,26 @@
+FROM golang:1.27 AS build
+WORKDIR /src
+COPY go.mod go.sum ./
+RUN go mod download
+COPY . .
+RUN CGO_ENABLED=0 go build -trimpath -o /pocketbase ./cmd/pocketbase && \
+    CGO_ENABLED=0 go build -trimpath -o /edge ./cmd/edge
+RUN mkdir -p /data/security && chown -R 65532:65532 /data
+
+FROM gcr.io/distroless/static-debian12:nonroot AS edge
+COPY --from=build /edge /edge
+EXPOSE 8080 8081
+HEALTHCHECK --interval=10s --timeout=3s --start-period=20s CMD ["/edge", "-probe", "http://127.0.0.1:8081/edge/readyz"]
+ENTRYPOINT ["/edge"]
+
+FROM gcr.io/distroless/static-debian12:nonroot AS pocketbase
+COPY --from=build /pocketbase /pocketbase
+COPY --from=build /edge /edge
+COPY --from=build --chown=65532:65532 /data /pb_data
+COPY --from=build --chown=65532:65532 /data/security /state
+COPY --chown=65532:65532 deploy/app /app
+EXPOSE 8090
+VOLUME ["/pb_data"]
+HEALTHCHECK --interval=10s --timeout=3s --start-period=20s CMD ["/edge", "-probe", "http://127.0.0.1:8090/api/health"]
+ENTRYPOINT ["/pocketbase"]
+CMD ["serve","--http=0.0.0.0:8090","--dir=/pb_data","--dev=false","--migrationsDir=/app/migrations","--hooksDir=/app/hooks","--publicDir=/app/public","--automigrate=false"]

package/FEATURES.md

@@ -0,0 +1,32 @@
+# Feature inventory
+
+All previously implemented work is represented here as add-on code or an explicit equivalent API. The dependency remains stock PocketBase; the old fork is not required to build or run this package.
+
+| Earlier work | Package implementation / current interface |
+|---|---|
+| Admission budgets, incident detection, management, temporary blocks, checkpoints | `security/`; native Security tab with overview, incident review, policy controls and shared superuser session. |
+| Local bounded simulation + database sandbox | `loadtest/`, `cmd/loadtest/`; same loopback safeguards, canaries, finite request/time limits. |
+| Encrypted manual/scheduled local/S3 backups | `backups/`; upstream ZIP snapshot hooks stage privately before age encryption. Key is supplied through an environment variable, never the UI/database. |
+| Backup upload/download/list/delete/restore | Native Backups list/download/delete/schedules remain. New encrypted upload under `/api/spink/backups/upload`; authenticated cancellation-aware restore, rollback on move/commit/restart errors; legacy ZIPs supported. |
+| #1154 JSON Schema | `features.JSONField` wraps original JSON field and overrides its public factory. Schema metadata survives serialization as `type: json`; inline Draft 2020-12 editor, format checks, bounded cache/depth, no external loading. |
+| #593 localized email | `mail/` hooks, request `?lang`, exact/parent fallback. Templates live in extension settings; UI is Settings → x47base extensions. Immutable request-scoped locale avoids cross-user leaks. `mail.WithLocale` supports Go callers. |
+| #3798 error localization | `localization.Register` opt-in catalogue. |
+| #159 singleton | `features.NewSingletonCollection`; original fixed-ID semantics. |
+| #401 color, #7752 dateOnly | Public field factories and native field editor additions. |
+| #6308 hasAny | Existing filter function syntax with permission/multi-relation tests. |
+| #7793 generate value | Field editor button; `/api/adapter/collections/{collection}/fields/{field}/generate`, superuser-only. |
+| #6667 duplicate record | `/api/collections/{collection}/records/{id}/duplicate`; checks source/protected files and internally forwards to stock create pipeline, preserving create rules/hooks. Base collections; 32MiB bounded clone, cloned files receive fresh native filenames. |
+| #7504 environment settings | `PB_SETTINGS_JSON` applied only on initial settings validation; existing saved values win. |
+| #4480 image dimensions | Authorized file hook with `?dimensions=1`, bounded image header read and width/height response headers. |
+| #7642 static fallback | `web.StaticWithOptions`; import changes, same fallback/error behavior. |
+| #7672 sidebar collapse | Native collection page toggle, independent desktop state. |
+| #7770 app name header | Mount extension reads existing app-name setting. |
+| #7556 OTP password seam | Opt-in `otp.Register(app, callback)` exposes `Request.Password` before stock OTP processing. Stock expiry/rate limits/single-use/MFA remain. It cannot add a field to the original core event; callback signature and timing differ from the fork. |
+| #7774 JSVM ProgramSource | Optional extension-owned `jsvm` loader with existing compiled-program callback, tests and stock core bindings. Included in the CLI with JS migrations and configurable hooks; Go embedders use this package instead of stock `plugins/jsvm`. Do not register both. |
+| Settings/collection watcher fix | `watcher.Register`, replacing pinned stock watcher hook IDs with coalesced pending settings/collection events. |
+
+The earlier decisions to defer native WebAuthn (#6800) and a new nested storage model (#2491) remain unchanged. Automatic attack classification/blocking, distributed load generation and proven production DDoS capacity were not previously implemented and are not claimed here.
+
+The experimental native UI integration and JSVM/watcher compatibility seams are version-pinned. Future PocketBase upgrades require this repository's checks and browser/restore verification; separation makes upgrades manageable, not automatically safe.
+
+The Docker edge add-on (`edge/`, `cmd/edge`, `deploy/`) now rejects public traffic before upstream work: explicit collections, CIDR/path blocks, synchronized enforce-mode family actions, bounded budgets/clients/concurrency/bodies, and separate operator capacity. Policy synchronization is asynchronous; existing requests are not recalled. Custom migrations/hooks/assets ship in the image. Gateway counters are local at `/edge/status`. See deployment docs for route and availability limits.

package/LICENSE.md

@@ -0,0 +1,17 @@
+The MIT License (MIT)
+Copyright (c) 2022 - present, Gani Georgiev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software
+and associated documentation files (the "Software"), to deal in the Software without restriction,
+including without limitation the rights to use, copy, modify, merge, publish, distribute,
+sublicense, and/or sell copies of the Software, and to permit persons to whom the Software
+is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or
+substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
+BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/MIGRATION.md

@@ -0,0 +1,49 @@
+# Integration and migration
+
+## Go application
+
+Use `require github.com/spink-dev/pocketbase-extension v0.0.0` and a **local** replace to `/Users/x47base/git/spink-dev_pocketbase-extension` until a release is published. Do not replace `github.com/pocketbase/pocketbase`.
+
+```go
+import (
+    "path/filepath"
+    "github.com/pocketbase/pocketbase"
+    extension "github.com/spink-dev/pocketbase-extension"
+)
+app := pocketbase.New()
+config := extension.DefaultConfig()
+statePath, err := filepath.Abs(filepath.Join(app.DataDir(), "security", "state.json"))
+if err != nil { panic(err) }
+config.StatePath = statePath
+if err := extension.Register(app, config); err != nil { panic(err) }
+if err := app.Start(); err != nil { panic(err) }
+```
+
+Register before bootstrap, so field factories, first-run settings and watcher hooks are ready. Registration is process-wide for field/filter factories; do not register competing JSON factory overrides or both versions of the extension. For Go embedders, `jsvm`, `otp`, and `localization` are explicit opt-ins. The packaged CLI includes JSVM/migration commands and static serving; use `--hooksDir`, `--migrationsDir`, `--hooksWatch`, `--publicDir` and `--staticFallback` to configure them. See FEATURES.md for the changed Go import paths.
+
+## Existing fork database
+
+1. Stop its server. Preserve the fork binary and an offline database backup, plus any backup/settings encryption keys.
+2. Work with an **offline copy** first. Run `go run ./cmd/import-fork --dir=/absolute/copy` before editing collections/settings through stock models. For encrypted native settings, also pass `--encryptionEnv=YOUR_EXISTING_SETTINGS_KEY_ENV` with the secret set in the environment.
+3. Import copies native `backups.encrypted/encryptionEnv` and per-template `locales` into extension-owned `_params.spink_extension_v1`. It preserves existing extension settings and is idempotent. Missing backup keys fail validation instead of disabling encryption. JSON `schema` is preserved by the registered field wrapper.
+4. Start the copied database using this package. Review Security, x47base extensions, field schemas, mail templates and a disposable backup/restore drill. Only then switch the live `--dir` during downtime.
+
+The current development database stays at `/Users/x47base/git/pocketbase/adapter/pb_data`; no account reset or data move is needed. The older deleted temporary database cannot be recovered by package extraction.
+
+## Backups
+
+Configure a secret of 32–1024 bytes in a server environment variable, default `PB_BACKUP_ENCRYPTION_KEY`. Restart with that variable available, then enable encryption in **Settings → x47base extensions**. Only its variable name is stored. Keep old keys while their archives remain in retention. Changing a key does not re-encrypt old backups.
+
+Normal/manual/scheduled backup creation uses the stock destination and consistency logic, with a private local staging directory and ciphertext-only final upload. Uploaded record files stored separately in S3 remain outside PocketBase database backups. Encrypted upload accepts `.zip.age`; normal ZIP upload remains native. Restore authenticates ciphertext before extracting or moving live files, checks cancellation and rolls back failed replacement. Like stock PocketBase, restore is a UNIX process restart operation.
+
+The extension owns the final restore handler at hook priority9999. Register application authorization/audit/exclusion hooks at ordinary/default priority and call `e.Next()`. Do not install another competing restore finalizer.
+
+## Upgrade and rollback
+
+Change the upstream version in go.mod, run `go mod tidy`, `./scripts/check.sh`, package inspection and browser/restore tests. The admin loader versions cached scripts by release and verifies the stock loader seam; no generated upstream files are edited. CSP and existing authenticated routes are retained. A normal reload picks up this installation.
+
+Do not run a plain stock executable against custom field metadata. Roll back with the preserved extension/fork binary and data backup if needed. This package has not been pushed or published; CI/container configuration has not run remotely.
+
+## Docker edge deployment
+
+New opt-in Compose deployment uses fresh named volumes and ports 8080/8081. It does not attach or migrate the existing host database. CLI adds `PB_SECURITY_STATE_PATH` (absolute), `PB_SECURITY_TRUSTED_PEERS`, `PB_SECURITY_MANAGEMENT_PEERS`, `PB_SECURITY_OPERATOR_PEERS` (comma-separated CIDRs; operator peers are runtime-only), and `PB_BACKUP_ENCRYPTION_KEY_FILE`. Existing persisted security policy retains precedence for peer lists; verify those after moving a database. Compose stores checkpoint state outside `pb_data` so native/encrypted restores can replace database files without moving a mounted state directory. Preserve and recover this volume separately. See deploy/README.md for deliberate public-route restrictions and migration packaging.

package/NOTICE.md

@@ -0,0 +1,5 @@
+# Source provenance
+
+PocketBase is copyright Gani Georgiev and contributors, licensed under MIT (see LICENSE.md). This extension includes adapted portions of the local PocketBase development fork, notably archive/restore helpers, watcher, custom fields and optional JSVM loader/bindings. The Go dependency is the unmodified upstream v0.40.3 module, not a vendored core fork.
+
+The JSVM declarations describe stock core APIs, with trailing whitespace normalized. Extension-specific Go callbacks are documented in their package sources. Upstream issue review history remains in the original local fork's research/2026-09-10 directory; this package's FEATURES.md records delivery scope without claiming upstream acceptance or issue closure.

package/README.md

@@ -0,0 +1,26 @@
+# @x47base/pocketbase-addon
+
+An independent add-on for **unmodified PocketBase v0.40.3**, including a native Security dashboard, encrypted backups and the development extensions listed in [FEATURES.md](FEATURES.md). Supports custom schemas, migrations, and hooks. Go 1.27+; Node 22+ only for npm/JavaScript tests. Co-developed with AI.
+
+
+```sh
+cd /Users/x47base/git/spink-dev_pocketbase-extension
+# Keep the admin account/database already created in this session:
+go run ./cmd/pocketbase serve --http=127.0.0.1:8090 --dir=/Users/x47base/git/pocketbase/adapter/pb_data
+# For a fresh instance instead, use --dir=./pb_data and complete first-run setup.
+```
+
+Admin: http://127.0.0.1:8090/_/ → **Security**. Backups: **Settings → Backups**. Encryption and localized mail: **Settings → x47base extensions**. Default security mode is observe; set `PB_SECURITY_MODE=enforce` only after reviewing limits. Stop any existing server on the same port first.
+
+```sh
+# From this folder, against your local instance:
+go run ./cmd/loadtest -target http://127.0.0.1:8090/api/health -rate 200 -clients 8 -duration 40s -requests 8000
+./scripts/check.sh
+npm pack --dry-run
+```
+
+The Go module is `github.com/spink-dev/pocketbase-extension`; the npm package is `@spink-dev/pocketbase-extension`. Neither has been published. Install locally with `npm install /Users/x47base/git/spink-dev_pocketbase-extension`, then `npx pocketbase-extension serve --dir=/absolute/pb_data`. The npm launcher builds the Go binary; this is not a browser-only SDK or a plugin for an already-built stock executable.
+
+See [integration and migration](MIGRATION.md), [feature inventory](FEATURES.md), [verification](VERIFY.md), and [deployment](deploy/README.md). The original development fork is historical; this repository is the extension source. Existing databases stay at their chosen `--dir` and are never moved automatically.
+
+Docker deployment with a pre-database gateway, private admin listener and versioned custom migrations: [deployment guide](deploy/README.md). It creates a separate database. Start with `docker compose -f deploy/compose.yaml up --build -d --wait`; admin is on `http://127.0.0.1:8081/_/`.

package/adapter.go

@@ -0,0 +1,31 @@
+package extension
+
+import (
+	"github.com/pocketbase/pocketbase/core"
+	"github.com/spink-dev/pocketbase-extension/admin"
+	"github.com/spink-dev/pocketbase-extension/backups"
+	"github.com/spink-dev/pocketbase-extension/features"
+	"github.com/spink-dev/pocketbase-extension/mail"
+	"github.com/spink-dev/pocketbase-extension/security"
+	"github.com/spink-dev/pocketbase-extension/settings"
+	"github.com/spink-dev/pocketbase-extension/watcher"
+)
+
+type Config = security.Config
+
+func DefaultConfig() Config { return security.DefaultConfig() }
+func Register(app core.App, config Config) error {
+	if err := security.Register(app, config); err != nil {
+		return err
+	}
+	features.Register(app)
+	settings.Register(app)
+	mail.Register(app)
+	watcher.Register(app)
+	backups.RegisterUpload(app)
+	backups.Register(app, func(a core.App) (backups.Config, error) { c, err := settings.Load(a); return c.Backups, err })
+	if err := admin.Register(app); err != nil {
+		return err
+	}
+	return nil
+}

package/admin/register.go

@@ -0,0 +1,60 @@
+package admin
+
+import (
+	"crypto/sha256"
+	"fmt"
+	"io/fs"
+	"regexp"
+	"strings"
+
+	"github.com/pocketbase/pocketbase/core"
+	"github.com/pocketbase/pocketbase/ui"
+)
+
+// Register versions the upstream extension loader without rebuilding its dashboard.
+func Register(app core.App) error {
+	if ui.DistDirFS == nil {
+		return nil
+	}
+	index, err := fs.ReadFile(ui.DistDirFS, "index.html")
+	if err != nil {
+		return err
+	}
+	pattern := regexp.MustCompile(`src="\./(assets/[^"?]+\.js)"`)
+	match := pattern.FindSubmatch(index)
+	if len(match) != 2 {
+		return fmt.Errorf("unsupported PocketBase admin entry point")
+	}
+	asset := string(match[1])
+	code, err := fs.ReadFile(ui.DistDirFS, asset)
+	if err != nil {
+		return err
+	}
+	if strings.Count(string(code), "/_/extensions.js") != 1 {
+		return fmt.Errorf("unsupported PocketBase extension loader")
+	}
+	version := fmt.Sprintf("%x", sha256.Sum256(append(code, []byte("spink-extension-0.1.0")...)))[:16]
+	versioned := strings.ReplaceAll(string(code), "/_/extensions.js", "/_/extensions.js?spink="+version)
+	html := pattern.ReplaceAllString(string(index), `src="./$1?spink=`+version+`"`)
+	app.OnServe().BindFunc(func(e *core.ServeEvent) error {
+		e.Router.BindFunc(func(re *core.RequestEvent) error {
+			if re.Request.Method != "GET" && re.Request.Method != "HEAD" {
+				return re.Next()
+			}
+			switch re.Request.URL.Path {
+			case "/_/", "/_/index.html":
+				if re.Response.Header().Get("Content-Security-Policy") == "" {
+					re.Response.Header().Set("Content-Security-Policy", "default-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' http://127.0.0.1:* https://tile.openstreetmap.org data: blob:; connect-src 'self' http://127.0.0.1:* https://nominatim.openstreetmap.org; script-src 'self' http://127.0.0.1:*; frame-ancestors 'none'")
+				}
+				re.Response.Header().Set("Cache-Control", "no-store")
+				return re.HTML(200, html)
+			case "/_/" + asset:
+				re.Response.Header().Set("Cache-Control", "no-store")
+				return re.Blob(200, "text/javascript", []byte(versioned))
+			}
+			return re.Next()
+		})
+		return e.Next()
+	})
+	return nil
+}

package/admin/register_test.go

@@ -0,0 +1,37 @@
+package admin
+
+import (
+	"github.com/pocketbase/pocketbase/apis"
+	"github.com/pocketbase/pocketbase/core"
+	"github.com/pocketbase/pocketbase/tests"
+	"net/http/httptest"
+	"strings"
+	"testing"
+)
+
+func TestAdminLoaderVersionsCachedExtensionURL(t *testing.T) {
+	a, err := tests.NewTestApp()
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer a.Cleanup()
+	if err = Register(a); err != nil {
+		t.Fatal(err)
+	}
+	r, _ := apis.NewRouter(a)
+	if err = a.OnServe().Trigger(&core.ServeEvent{App: a, Router: r}); err != nil {
+		t.Fatal(err)
+	}
+	h, err := r.BuildMux()
+	if err != nil {
+		t.Fatal(err)
+	}
+	w := httptest.NewRecorder()
+	h.ServeHTTP(w, httptest.NewRequest("GET", "/_/", nil))
+	if !strings.Contains(w.Header().Get("Content-Security-Policy"), "frame-ancestors 'none'") {
+		t.Fatal("missing dashboard CSP")
+	}
+	if w.Code != 200 || !strings.Contains(w.Body.String(), "?spink=") || w.Header().Get("Cache-Control") != "no-store" {
+		t.Fatal("admin HTML did not version entry")
+	}
+}

package/backups/backup_encryption_test.go

@@ -0,0 +1,82 @@
+package backups
+
+import (
+	"archive/zip"
+	"context"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestBackupEncryptionRoundTripAndTamper(t *testing.T) {
+	t.Setenv("PB_TEST_BACKUP_KEY", strings.Repeat("a", 32))
+	cfg := Config{Encrypted: true, EncryptionEnv: "PB_TEST_BACKUP_KEY"}
+	dir := t.TempDir()
+	source := filepath.Join(dir, "plain.zip")
+	f, err := os.Create(source)
+	if err != nil {
+		t.Fatal(err)
+	}
+	z := zip.NewWriter(f)
+	entry, err := z.Create("data.db")
+	if err != nil {
+		t.Fatal(err)
+	}
+	entry.Write([]byte("database fixture"))
+	z.Close()
+	f.Close()
+	encrypted, err := encryptBackup(context.Background(), cfg, source)
+	if err != nil {
+		t.Fatal(err)
+	}
+	raw, err := os.ReadFile(encrypted)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.HasPrefix(string(raw), EncryptedBackupHeader) {
+		t.Fatal("not age format")
+	}
+	restored := filepath.Join(dir, "restored")
+	if err := extractBackup(context.Background(), cfg, encrypted, restored); err != nil {
+		t.Fatal(err)
+	}
+	data, err := os.ReadFile(filepath.Join(restored, "data.db"))
+	if err != nil || string(data) != "database fixture" {
+		t.Fatal("round trip changed data")
+	}
+	if err := extractBackup(context.Background(), cfg, source, filepath.Join(dir, "downgrade"), "backup.zip.age"); err == nil {
+		t.Fatal("encrypted backup accepted plaintext replacement")
+	}
+	legacy := filepath.Join(dir, "legacy")
+	if err := extractBackup(context.Background(), Config{}, source, legacy); err != nil {
+		t.Fatal(err)
+	}
+	t.Setenv("PB_TEST_BACKUP_KEY", strings.Repeat("b", 32))
+	if err := extractBackup(context.Background(), cfg, encrypted, filepath.Join(dir, "wrong-key")); err == nil {
+		t.Fatal("accepted wrong key")
+	}
+	t.Setenv("PB_TEST_BACKUP_KEY", strings.Repeat("a", 32))
+	raw[len(raw)-1] ^= 1
+	os.WriteFile(encrypted, raw, 0600)
+	target := filepath.Join(dir, "tampered")
+	if err := extractBackup(context.Background(), cfg, encrypted, target); err == nil {
+		t.Fatal("accepted corrupt stream")
+	}
+	if _, err := os.Stat(target); !os.IsNotExist(err) {
+		t.Fatal("extracted before authenticating")
+	}
+	leftovers, _ := filepath.Glob(filepath.Join(dir, "pb_decrypted_*"))
+	if len(leftovers) != 0 {
+		t.Fatal("leaked plaintext temporary file")
+	}
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+	if _, err := encryptBackup(ctx, cfg, source); err == nil {
+		t.Fatal("ignored cancellation")
+	}
+	t.Setenv("PB_TEST_BACKUP_KEY", "")
+	if _, err := encryptBackup(context.Background(), cfg, source); err == nil {
+		t.Fatal("missing key accepted")
+	}
+}

package/backups/encryption.go

@@ -0,0 +1,138 @@
+package backups
+
+import (
+	"bufio"
+	"context"
+	"errors"
+	"io"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strings"
+
+	"filippo.io/age"
+	"github.com/spink-dev/pocketbase-extension/internal/archive"
+)
+
+const EncryptedBackupHeader = "age-encryption.org/v1\n"
+
+var backupEnvPattern = regexp.MustCompile(`^[A-Za-z_][A-Za-z0-9_]{0,127}$`)
+
+func (c Config) encryptionKey() (string, error) {
+	name := c.EncryptionEnv
+	if name == "" {
+		name = "PB_BACKUP_ENCRYPTION_KEY"
+	}
+	if !backupEnvPattern.MatchString(name) {
+		return "", errors.New("invalid backup encryption environment name")
+	}
+	key := os.Getenv(name)
+	if len(key) < 32 || len(key) > 1024 {
+		return "", errors.New("backup encryption key must contain 32 to 1024 bytes")
+	}
+	return key, nil
+}
+
+type backupContextReader struct {
+	ctx context.Context
+	r   io.Reader
+}
+
+func (r backupContextReader) Read(p []byte) (int, error) {
+	if err := r.ctx.Err(); err != nil {
+		return 0, err
+	}
+	return r.r.Read(p)
+}
+func encryptBackup(ctx context.Context, c Config, source string) (string, error) {
+	key, err := c.encryptionKey()
+	if err != nil {
+		return "", err
+	}
+	input, err := os.Open(source)
+	if err != nil {
+		return "", err
+	}
+	defer input.Close()
+	output, err := os.CreateTemp(filepath.Dir(source), "pb_encrypted_*")
+	if err != nil {
+		return "", err
+	}
+	success := false
+	defer func() {
+		output.Close()
+		if !success {
+			os.Remove(output.Name())
+		}
+	}()
+	recipient, err := age.NewScryptRecipient(key)
+	if err != nil {
+		return "", errors.New("invalid backup encryption key")
+	}
+	recipient.SetWorkFactor(18)
+	writer, err := age.Encrypt(output, recipient)
+	if err != nil {
+		return "", err
+	}
+	if _, err = io.Copy(writer, backupContextReader{ctx, input}); err != nil {
+		return "", err
+	}
+	if err = writer.Close(); err != nil {
+		return "", err
+	}
+	if err = output.Close(); err != nil {
+		return "", err
+	}
+	success = true
+	return output.Name(), nil
+}
+func extractBackup(ctx context.Context, c Config, source, dest string, originalName ...string) error {
+	input, err := os.Open(source)
+	if err != nil {
+		return err
+	}
+	defer input.Close()
+	buffered := bufio.NewReader(input)
+	header, _ := buffered.Peek(len(EncryptedBackupHeader))
+	if string(header) != EncryptedBackupHeader {
+		if len(originalName) > 0 && strings.HasSuffix(originalName[0], ".age") {
+			return errors.New("encrypted backup header is missing or invalid")
+		}
+		return archive.ExtractContext(ctx, source, dest)
+	}
+	key, err := c.encryptionKey()
+	if err != nil {
+		return err
+	}
+	identity, err := age.NewScryptIdentity(key)
+	if err != nil {
+		return errors.New("invalid backup encryption key")
+	}
+	identity.SetMaxWorkFactor(18)
+	reader, err := age.Decrypt(backupContextReader{ctx, buffered}, identity)
+	if err != nil {
+		return errors.New("cannot decrypt backup with configured key")
+	}
+	output, err := os.CreateTemp(filepath.Dir(dest), "pb_decrypted_*")
+	if err != nil {
+		return err
+	}
+	defer os.Remove(output.Name())
+	defer output.Close()
+	if _, err = io.Copy(output, reader); err != nil {
+		return errors.New("backup authentication failed or restore was cancelled")
+	}
+	if err = output.Close(); err != nil {
+		return err
+	}
+	if err = ctx.Err(); err != nil {
+		return err
+	}
+	return archive.ExtractContext(ctx, output.Name(), dest)
+}
+func EncryptedBackupName(name string, enabled bool) string {
+	if enabled && !strings.HasSuffix(name, ".age") {
+		return name + ".age"
+	}
+	return name
+}

package/backups/integration_test.go

@@ -0,0 +1,51 @@
+package backups_test
+
+import (
+	"context"
+	"github.com/spink-dev/pocketbase-extension/backups"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/pocketbase/pocketbase/core"
+	"github.com/pocketbase/pocketbase/tests"
+)
+
+func TestEncryptedBackupIntegration(t *testing.T) {
+	app, err := tests.NewTestApp()
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer app.Cleanup()
+	t.Setenv("PB_BACKUP_TEST_KEY", strings.Repeat("x", 32))
+	backups.Register(app, func(core.App) (backups.Config, error) {
+		return backups.Config{Encrypted: true, EncryptionEnv: "PB_BACKUP_TEST_KEY"}, nil
+	})
+	if err := app.CreateBackup(context.Background(), "encrypted.zip"); err != nil {
+		t.Fatal(err)
+	}
+	path := filepath.Join(app.DataDir(), core.LocalBackupsDirName, "encrypted.zip.age")
+	raw, err := os.ReadFile(path)
+	if err != nil || !strings.HasPrefix(string(raw), backups.EncryptedBackupHeader) {
+		t.Fatal("backup was not encrypted")
+	}
+	t.Setenv("PB_BACKUP_TEST_KEY", "")
+	if err := app.CreateBackup(context.Background(), "missing.zip"); err == nil {
+		t.Fatal("missing key accepted")
+	}
+	if _, err := os.Stat(filepath.Join(app.DataDir(), core.LocalBackupsDirName, "missing.zip.age")); !os.IsNotExist(err) {
+		t.Fatal("uploaded without key")
+	}
+	before, err := app.CountRecords("users")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := app.RestoreBackup(context.Background(), "encrypted.zip.age"); err == nil {
+		t.Fatal("restored without key")
+	}
+	after, err := app.CountRecords("users")
+	if err != nil || before != after {
+		t.Fatal("failed restore changed live database")
+	}
+}