@x47base/pocketbase-addon 0.1.0 → 0.2.0

package/Dockerfile

@@ -4,20 +4,28 @@ 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
+    CGO_ENABLED=0 go build -trimpath -o /edge ./cmd/edge && \
+    CGO_ENABLED=0 go build -trimpath -o /gateway ./cmd/gateway
 RUN mkdir -p /data/security && chown -R 65532:65532 /data
 
 FROM gcr.io/distroless/static-debian12:nonroot AS edge
 COPY --from=build /edge /edge
+COPY --from=build --chown=65532:65532 /data/security /telemetry
 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 gateway
+COPY --from=build /gateway /gateway
+EXPOSE 8095
+ENTRYPOINT ["/gateway","-listen",":8095","-config","/config/gateway.json"]
+
 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 --from=build --chown=65532:65532 /data/security /telemetry
 COPY --chown=65532:65532 deploy/app /app
 EXPOSE 8090
 VOLUME ["/pb_data"]

package/FEATURES.md

@@ -30,3 +30,20 @@ The earlier decisions to defer native WebAuthn (#6800) and a new nested storage
 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.
+
+## Firewall visibility and upload hardening
+
+Native Security now separates public firewall metrics from application traffic,
+shows rejection reasons, body bytes versus declared sizes, one-second traffic
+buckets, upstream health and effective upload/concurrency limits. Every edge denial
+is retained immediately as a grouped policy event. Imported events use the existing
+incident review and acknowledgement workflow. Missing/stale telemetry is explicit.
+Public uploads have bounded buffers, a five-second default body deadline and a
+four-request default client concurrency limit. No change grants guaranteed uptime
+or classifies every rejected request as a malicious attack.
+
+## Unified optional features
+
+- `hosting/`: named backup targets, superuser backup policies and native Hosting dashboard; enabled by `HOSTING_ADDON_CONFIG` in the CLI. Includes commerce deployment rendering and DNS/route tools.
+- `multinode/`, `cmd/gateway`: explicit host-to-owner routing with opt-in bounded public response caching. Runs independently from the database server.
+- `pocketbase-addon init`: generates missing development configuration without overwriting operator files. All sources and guides ship in the npm tarball.

package/MIGRATION.md

@@ -2,7 +2,15 @@
 
 ## 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`.
+Install `@x47base/pocketbase-addon` with npm (or install its local `.tgz` before publication). In your Go host, use:
+
+```sh
+go mod edit -require=github.com/spink-dev/pocketbase-extension@v0.0.0
+go mod edit -replace=github.com/spink-dev/pocketbase-extension=./node_modules/@x47base/pocketbase-addon
+go mod tidy
+```
+
+Do not replace `github.com/pocketbase/pocketbase`. Node is only needed for package installation; production may run the compiled Go binary.
 
 ```go
 import (
@@ -28,7 +36,7 @@ Register before bootstrap, so field factories, first-run settings and watcher ho
 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.
+Keep the existing database at its explicit `--dir`; package installation never moves or resets it.
 
 ## Backups
 
@@ -47,3 +55,44 @@ Do not run a plain stock executable against custom field metadata. Roll back wit
 ## 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.
+
+## Security observability update
+
+- Deploy the new PocketBase and edge binaries together. For Docker, use the updated
+  Compose template's separate telemetry volume and flags; see deploy/README.md.
+  `Config.EdgeStatePath` is runtime-only and survives policy edits/reloads.
+- `/api/security/status` adds `edge`, `edgeConfigured`, and `edgeStale`.
+  `/edge/status` preserves `accepted` (alias of `forwarded`) and adds the versioned
+  aggregate telemetry contract. Existing admission policy fields remain valid.
+- `TrafficWindow.seconds` describes the actual evaluation interval; clients must
+  divide counts by it instead of assuming ten seconds. Application evaluation now
+  occurs every second; incident evidence accumulates across suspicious windows.
+- Incidents add optional `source`, `sourceId`, `reason`, and `severity`; historical
+  incidents without a source represent PocketBase. Edge incidents share the existing
+  ID/cursor/acknowledgement API. Old evidence cannot be reconstructed retrospectively.
+- Edge policy adds `bodyReadTimeoutSeconds` (default 5, range 1–10) and
+  `maxClientConcurrent` (default min(4, maxConcurrent)). Slow legitimate uploads may
+  need an explicit policy adjustment. These limits apply to the public listener.
+- Snapshots/checkpoints remain best-effort and bounded. Retain the security volume
+  for incident history. Firewall process counters reset on gateway restart.
+
+- The application operator lane now matches the gateway capacity of eight requests,
+  allowing parallel admin resources without prematurely exhausting the previous
+  four-request application lane. Authentication requirements are unchanged.
+
+## Unified hosting and multinode package
+
+Install only `@x47base/pocketbase-addon` for these features. Change Go imports:
+
+| Previous import | Combined import |
+|---|---|
+| `github.com/spink-dev/pocketbase-hosting-addon` | `github.com/spink-dev/pocketbase-extension/hosting` |
+| `github.com/spink-dev/pocketbase-multinode-addon` | `github.com/spink-dev/pocketbase-extension/multinode` |
+
+Remove the two old Go require/replace entries and npm dependencies after updating imports. Register hosting once, after the base add-on, or use the bundled CLI with `HOSTING_ADDON_CONFIG`. Keep existing JSON configurations, environment names, policy/run collections and data directories. Existing separate package installations are unchanged until migrated; fixes in this combined package do not patch those installations automatically.
+
+Fresh CLI configurations now default to `enforce`. Existing persisted policy wins; inspect the Security dashboard when upgrading. Go `DefaultConfig()` retains its prior observe default for embedding compatibility. Explicitly choose enforce for new production hosts.
+
+Backup/restore finalizers now share a process-local admission lock even without hosting. Local hosting destinations inside the data tree outside its excluded `backups` directory are rejected. Move such archives offline to an external backup location and update server configuration before enabling hosting; no archive is moved automatically.
+
+The gateway strips `X-Spink-Operator` and `X-Real-IP`. Public callers cannot nominate the private operator lane. Request socket deadlines enforce the existing two-minute maximum; streaming clients must reconnect. The bundled gateway accepts at most 512 simultaneous connections. Custom Go hosts must also bound their HTTP listeners.

package/NOTICE.md

@@ -3,3 +3,5 @@
 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.
+
+The hosting and multinode source directories were consolidated from the local spink-dev_pocketbase-hosting-addon and spink-dev_pocketbase-multinode-addon repositories. Their prior npm package identities are superseded for this distribution; the original checkouts are preserved.

package/README.md

@@ -1,26 +1,66 @@
 # @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.
+One npm package for stock **PocketBase v0.40.3** extensions: security controls and dashboard, encrypted backups, hosting backup policies, single-owner tenant routing, JavaScript hooks/migrations, and custom field features. See [FEATURES.md](FEATURES.md).
 
+## Install and start
+
+Requires **Node.js 22+** and **Go 1.27+** on the server/build machine. This npm package includes Go source and builds a server; it is not a browser SDK or a plugin loaded into an existing stock executable. You do not need a GitHub account, checkout, or Git installation.
+
+Once this version is published to npm:
 
 ```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.
+mkdir my-pocketbase
+cd my-pocketbase
+npm init -y
+npm install --save-exact @x47base/pocketbase-addon
+npx pocketbase-addon init
+PB_SECURITY_MODE=enforce npx pocketbase-addon serve --http=127.0.0.1:8090 --dir=./pb_data
 ```
 
-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.
+Open **http://127.0.0.1:8090/_/** and complete first-run superuser setup. `init` writes missing `hosting.json` and `gateway.json` with private file permissions; existing files are preserved. It does not start services or create accounts. Keep the database, configuration and secrets outside `node_modules`.
+
+**This checkout has not been published by this change.** To test before publication, run `npm pack` in the package directory and install the resulting `.tgz` in your application with `npm install /absolute/path/to/package.tgz`. The commands above then work unchanged. The tarball includes source, UI assets, examples, deployment tools and documentation.
+
+The first build downloads pinned Go dependencies. Every launch runs `go build` using Go's build cache. To require module-proxy downloads without direct GitHub access, set `GOPROXY=https://proxy.golang.org` (without `,direct`); proxy availability is then required. The Go module name remains `github.com/spink-dev/pocketbase-extension` for import compatibility; that name is not an installation instruction.
+
+## Choose features
+
+| Feature | How to enable |
+|---|---|
+| Security dashboard, field extensions, backups | Included in `serve`; Security is in the native admin UI. Fresh CLI configurations enforce admission limits. Existing persisted security policy retains precedence. |
+| JavaScript hooks and migrations | `--hooksDir=./pb_hooks --migrationsDir=./pb_migrations`; use `--automigrate=false` in production. |
+| Static content | `--publicDir=./pb_public`; `--staticFallback=` disables fallback. |
+| Hosting backup schedules/dashboard | Set `HOSTING_ADDON_CONFIG=./hosting.json` before `serve`. Off when unset. |
+| Tenant routing gateway | Separate process: `npx pocketbase-addon gateway -config ./gateway.json -listen 127.0.0.1:8095`. |
+| Public API security edge | `npx pocketbase-addon edge -help`; see [deployment guide](deploy/README.md). |
+| Deployment rendering | `npx pocketbase-addon hosting -blueprint ./blueprint.json -out ./generated`. |
+
+`pocketbase-extension` remains an alias for existing scripts. `loadtest` and `import-fork` commands remain available. Use `npx pocketbase-addon <command> -help` for gateway/edge/hosting flags and `npx pocketbase-addon serve --help` for PocketBase flags.
+
+### Hosting and encrypted backups
 
 ```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
+HOSTING_ADDON_CONFIG=./hosting.json PB_SECURITY_MODE=enforce \
+  npx pocketbase-addon serve --http=127.0.0.1:8090 --dir=./pb_data
 ```
 
-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.
+In **Hosting**, create a paused backup policy, run it manually and verify the snapshot before enabling its schedule. The generated configuration uses PocketBase's native backup destination. Additional named local and S3-compatible targets are documented in [hosting](hosting/README.md).
+
+For encryption, supply a 32–1024-byte secret via `PB_BACKUP_ENCRYPTION_KEY` or a secret file referenced by `PB_BACKUP_ENCRYPTION_KEY_FILE`. Enable encryption under **Settings → x47base extensions**. Keys stay in the server environment, not records or generated files. Named S3 targets refuse plaintext writes. Keep keys separately from snapshots and test restoration on a disposable copy. Local destinations must be outside `pb_data` or below `pb_data/backups`; recursive destinations are rejected, including symlink aliases.
+
+### Multiple owners
+
+The generated gateway config is a **loopback development example**, accepting `Host: localhost:8095` and forwarding to port 8090. It does not enable caching or restrict routes. For production, configure explicit hosts/private origins, TLS ingress and appropriate route restrictions using the [gateway guide](multinode/README.md). Never expose the example origin directly.
+
+Every tenant has exactly one authoritative PocketBase owner and its own assigned data partition. Gateways may scale; SQLite writers must not share a data directory. No automatic owner failover, replication, distributed rate limit or guaranteed DDoS capacity is provided. Public caching is opt-in; authenticated requests and writes bypass it. The gateway limits admitted requests, body size, connection count and request lifetime.
+
+Store-bound gateway routes and the hosting **commerce blueprint** require the separate Vendure integration and application-level domain guards. Combining hosting/multinode does not add a commerce application to this package. Generic PocketBase usage needs neither Vendure nor PostgreSQL.
+
+## Production and development
 
-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.
+- Start with [deployment](deploy/README.md) for the private owner/operator listener and public API edge. Container builds from the installed source support `--target pocketbase`, `--target edge`, and `--target gateway`.
+- Read [integration/migration](MIGRATION.md) before changing an existing host or database. No automatic data moves or account resets occur.
+- Run `npm run check` in the package source for Go tests, race tests, vet, JavaScript tests and CLI builds. Tests use disposable databases and local HTTP servers.
+- See [security review](SECURITY-REVIEW.md) for confirmed high-severity findings, trigger scenarios, fixes and verification limits.
 
-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/_/`.
+Co-developed with AI. MIT license; see [NOTICE.md](NOTICE.md) for third-party notices.

package/SECURITY-REVIEW.md

@@ -0,0 +1,96 @@
+# Security and reliability review
+
+Reviewed 2026-09-15. Scope: the base extension's authorization/admission, backup/restore and duplication boundaries; hosting configuration, schedules, retention and generated deployments; multinode routing, caching, forwarding and resource admission. Findings below are restricted to **High** severity. No Critical issue was confirmed. This is source review with local regression tests, not a production security certification.
+
+## 1. High — concurrent backup/restore finalizers can operate on the same files
+
+**Failure mode:** The pinned upstream `CreateBackup`/`RestoreBackup` entrypoints check `Store.Has` and then call `Store.Set` separately. Both operations are thread-safe individually, but this is not atomic admission. The base extension had no independent lock. Concurrent callers can enter snapshot/restore finalizers together, sharing temporary database filenames, filesystem hook IDs and live data files. One caller can remove shared temporary state or replace files while another is using them. Hosting had its own guard, but users of the base package alone were unprotected.
+
+**Trigger:** Two callers both observe no active backup before either stores its active marker. Run backup versus backup, or backup versus restore. This requires overlapping administrative/scheduled/application operations; it is not an unauthenticated endpoint bypass.
+
+**Corrected code:** [backups/register.go](backups/register.go) installs the same mutex around both hook chains, before the hosting/encryption/finalizer handlers:
+
+```go
+var operation sync.Mutex
+ guard := func(e *core.BackupEvent) error {
+    if !operation.TryLock() {
+        return errors.New("backup/restore operation already running")
+    }
+    defer operation.Unlock()
+    return e.Next()
+}
+app.OnBackupCreate().Bind(&hook.Handler[*core.BackupEvent]{
+    Id: "spink.backup.guard", Priority: -2000, Func: guard,
+})
+app.OnBackupRestore().Bind(&hook.Handler[*core.BackupEvent]{
+    Id: "spink.restore.guard", Priority: -2000, Func: guard,
+})
+```
+
+**Regression:** `TestBackupAndRestoreHooksExcludeConcurrentOperations` reproduces the state after both callers passed upstream admission and proves the second finalizer is rejected. It fails against the original base implementation. The lock is per registration/process; it does not make shared-data multi-writer operation safe.
+
+## 2. High — public clients can nominate the private operator lane
+
+**Failure mode:** The multinode proxy rebuilt standard forwarded headers but preserved `X-Spink-Operator`. The base security layer grants a reserved management lane when that header is `1` and the network peer is in `OperatorPeers`. When a gateway peer is in that configured set, public callers can bypass ordinary admission and occupy operator capacity. This threatens management availability; it does **not** bypass PocketBase superuser authentication.
+
+**Trigger:** Configure the owner to accept the multinode gateway's source address as an operator peer, then send an ordinary proxied request with `X-Spink-Operator: 1`. Eight concurrent long requests can consume the reserved lane. The condition does not apply when the gateway peer is outside `OperatorPeers` or a sanitizing edge removes the header first.
+
+**Corrected code:** [multinode/gateway.go](multinode/gateway.go), inside proxy `Rewrite`, before rebuilding forwarded identity:
+
+```go
+pr.Out.Header.Del("X-Spink-Operator")
+pr.Out.Header.Del("X-Real-IP")
+pr.SetXForwarded()
+```
+
+**Regression:** `TestGatewayStripsPrivateOperatorIdentity` sends forged private/forwarded identity and checks exactly what the origin receives. It fails against the original gateway.
+
+## 3. High — non-reading clients can permanently hold gateway admission slots
+
+**Failure mode:** A two-minute request context cancels upstream work but does not interrupt a blocked write to the downstream socket. The original gateway server had no write timeout. Once an upstream response fills socket buffers for a client that stops reading, `ReverseProxy` can remain in `Write` beyond the context deadline, retaining its admission slot. Exhausting the default 128 slots prevents ordinary service. Connections themselves were also unbounded at the listener.
+
+**Trigger:** Open requests to a configured tenant endpoint returning a sufficiently large response, then stop reading while keeping TCP open. Repeat up to the configured `maxConcurrent`. The regression uses one slot, a bounded large response and a shortened request context to reproduce it locally without a load attack.
+
+**Corrected code:** [multinode/gateway.go](multinode/gateway.go), after deriving the existing bounded request context:
+
+```go
+deadline, _ := ctx.Deadline()
+controller := http.NewResponseController(w)
+_ = controller.SetReadDeadline(deadline)
+_ = controller.SetWriteDeadline(deadline)
+defer controller.SetReadDeadline(time.Time{})
+defer controller.SetWriteDeadline(time.Time{})
+```
+
+[cmd/gateway/main.go](cmd/gateway/main.go) also serves through `netutil.LimitListener(listener, 512)`. Standard Go HTTP writers support these deadlines; custom embedding writers must preserve `ResponseController` support. Streaming clients must reconnect within the existing two-minute lifetime.
+
+**Regressions:** `TestSlowReaderReleasesAdmissionSlot` uses a real TCP client that does not read; `TestGatewaySetsSocketDeadlinesForAdmittedRequests` checks deadline setup/reset. Both fail against the original gateway.
+
+## 4. High — local backup targets can recursively archive prior backups
+
+**Failure mode:** Hosting validated only that a local path was absolute. A target such as `/data/archives` is inside the directory PocketBase snapshots and outside its excluded `/data/backups` subtree. Every later snapshot includes previous archives. With retention greater than one, nested archive growth can exhaust the owner's disk, stopping both writes and backups. Retention runs only after creating the next snapshot, too late to prevent exhaustion.
+
+**Trigger:** With `--dir=/data`, configure a named local target `/data/archives`, schedule repeated backups and keep multiple snapshots. A symlink outside the data directory pointing into that subtree has the same effect.
+
+**Corrected code:** [hosting/config.go](hosting/config.go) adds `resolvedPath` and `validateLocalTarget`, resolving existing ancestors for destinations that do not yet exist. Only physical paths outside the data tree or under its excluded `backups` subtree pass. [hosting/backups.go](hosting/backups.go) applies this at startup and every destination opening:
+
+```go
+if err := validateLocalTarget(app.DataDir(), t.Path); err != nil {
+    return nil, err
+}
+```
+
+**Regression:** `TestLocalTargetCannotIncludeBackupsInNextSnapshot` covers the data root, nested paths, symlink aliases, allowed external paths and allowed native-backup descendants. Server-controlled filesystem paths remain a trusted configuration boundary; do not allow untrusted local users to change their ancestors concurrently.
+
+## Other reviewed boundaries
+
+- Management/settings/hosting routes require native superuser authentication. Record duplication checks view/protected-file access and invokes the native create pipeline. No new authorization bypass was confirmed in these paths.
+- Gateway destinations come from validated server configuration, not request URLs. Unknown hosts fail closed. Cache keys separate hosts and paths; credentialed/variant requests and private responses bypass caching. Mutations have no application retry/failover.
+- Named S3 destinations use configured HTTPS endpoints and credential environment references; plaintext backup uploads are rejected. Restore authenticates encrypted content before extraction and retains cancellation/rollback handling. Existing ZIP path traversal defenses remain.
+- Configuration/route counts, cache size, bodies, request admission and policy query sizes have explicit bounds. Snapshot size, backup history and deployment capacity remain operational concerns, not unlimited-capacity guarantees.
+
+## Delivery and verification
+
+Fixes live in the combined `@x47base/pocketbase-addon` source. The two original standalone checkouts are preserved; their installations must migrate to receive these patches. The root README and MIGRATION guide describe npm tarball installation and changed imports. No upstream PocketBase source/module cache was modified.
+
+See the current verification section in [VERIFY.md](VERIFY.md). Local checks do not establish public TLS, real cloud storage delivery, Kubernetes admission/scheduling, browser UI correctness, volumetric DDoS resistance or a real production restore drill. No npm publication or provider deployment is part of this change.

package/VERIFY.md

@@ -0,0 +1,34 @@
+# Verification — unified package, 2026-09-15
+
+- `GOWORK=off sh scripts/check.sh`: passed. Includes all-package Go tests, targeted race tests (including hosting and multinode), `go vet ./...`, 13 JavaScript tests, and builds of PocketBase, edge, gateway and hosting commands.
+- New backup admission and gateway operator/deadline/slow-reader regressions fail against the original implementations and pass against the patched combined source. Slow-reader coverage uses an actual TCP connection and a short fixture timeout, not a public load test.
+- Local target validation covers missing descendants, symlink aliases and allowed external/native-backup destinations. Generated gateway routes are validated against the gateway's actual configuration contract, including the 64-character store bound.
+- npm tarball inventory includes hosting/multinode source, UI, examples, tools and guides, and excludes live databases, environment files and Git metadata.
+- A fresh consumer installed the `.tgz` with `npm install --offline --ignore-scripts`. With `GOPROXY=off` and previously cached Go dependencies, the installed launcher generated configuration and rendered manifests, started an owner and gateway on loopback, proxied a real health request, created hosting collections and denied unauthenticated hosting API access. Temporary processes were stopped.
+- No npm publication, Docker image build, provider deployment, Kubernetes scheduling, browser UI check or new process-restarting restore drill was performed for this consolidation. Historical results below are previous verification, not rerun claims.
+
+## Historical verification
+
+# Verification — 2026-09-10
+
+- Independent `GOWORK=off` module resolves unmodified `github.com/pocketbase/pocketbase v0.40.3`, with no upstream replacement. Original fork is not required.
+- Go tests for all packages, race checks for security/features/localization/loadtest/backups/settings/mail/admin/OTP/watcher, vet, Node model/registration tests and binary build passed.
+- Migrated regression cases cover schema precision and remote-reference denial, duplicate source/create/protected-file rules and cloned file contents, static fallback, authorized image dimensions, first-run environment settings, watcher coalescing, settings revision conflicts, locale isolation and native OTP single-use.
+- Encryption tests cover age round trip, wrong/missing keys, tampering, plaintext downgrade, cancellation, private staging and S3-compatible HTTP destination receiving ciphertext only. This is an isolated S3-compatible fixture, not a live cloud-provider verification.
+- Restore swap tests inject second-move and transaction-commit failures and cancellation; originals are restored. A later registered ordinary-priority application restore hook still runs.
+- Real isolated process drill: create database/record → encrypted backup → mutate record → restore through native API → process restart → original record restored, same admin token valid. Temporary database and process were removed.
+- Browser reproduced missing Security on the existing 127.0.0.1 session. Versioned upstream entry/extension loader restored the native Security link; overview loaded without a new login. Server HTML retains stock CSP. No generated upstream source or bundle was changed.
+- Final browser review confirmed Settings → x47base extensions exposes encryption/key-availability, encrypted upload and localized-template controls; the Security overview remains reachable with the existing session.
+- npm package dry run includes Go sources, UI, launcher and required module/type assets, excludes database files. npm CLI builds and displays help; the extracted npm archive builds independently. Nothing pushed or published.
+- Dockerfile and GitHub workflow supplied; neither was run remotely. No production DDoS capacity, automatic attacker attribution, or future-version compatibility claim.
+
+## Docker edge add-on
+
+- Full Go tests, race checks (including edge), vet, Node tests and both binaries pass.
+- Both Docker image targets build locally; isolated Compose deployment reaches healthy on ports 18080/18081 with fresh named volumes. No existing development database is attached.
+- Gateway regression tests prove zero upstream calls for blocked networks/paths/families, unknown/admin routes, ambiguous paths, malformed policy and oversized/chunked bodies. Tests cover client bounds, unchanged-reload budgets, stale checkpoints, action expiry, forwarded-header spoofing, and independent operator capacity.
+- Native operator tests require an explicit immediate peer and marker; untrusted requests remain blocked and native superuser authentication remains required.
+- Real Docker drill: checked-in notes migration applies; authenticated public read succeeds; a temporary dashboard API block synchronizes; 100 blocked reads produce zero forwarded requests; operator reads remain available; removing the block recovers public reads. Native backup → mutate → restore succeeds inside the container with the separate state volume.
+- Additional finite smoke: 200 public admin-path requests all rejected, zero public accepted delta, liveness and readiness canaries pass.
+- npm package inspection includes edge sources, Dockerfile, Compose, migration and deployment guide. CI now builds images and runs a disposable Compose smoke; remote CI has not run.
+- These are functional, local checks, not a production capacity benchmark or proof against volumetric DDoS. Gateway policy sync is asynchronous and the documented stale checkpoint bound applies.

package/backups/concurrency_test.go

@@ -0,0 +1,43 @@
+package backups
+
+import (
+	"context"
+	"errors"
+	"github.com/pocketbase/pocketbase/core"
+	"github.com/pocketbase/pocketbase/tests"
+	"testing"
+)
+
+func TestBackupAndRestoreHooksExcludeConcurrentOperations(t *testing.T) {
+	app, err := tests.NewTestApp()
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer app.Cleanup()
+	Register(app, func(core.App) (Config, error) { return Config{}, nil })
+	entered, release, done := make(chan struct{}), make(chan struct{}), make(chan error, 1)
+	event := func() *core.BackupEvent {
+		return &core.BackupEvent{App: app, Context: context.Background(), Name: "backup.zip"}
+	}
+	go func() {
+		done <- app.OnBackupCreate().Trigger(event(), func(e *core.BackupEvent) error { close(entered); <-release; return nil })
+	}()
+	<-entered
+	defer func() {
+		close(release)
+		if err := <-done; err != nil {
+			t.Error(err)
+		}
+	}()
+	// Trigger represents two callers already past the upstream Has/Set busy check.
+	called := false
+	err = app.OnBackupCreate().Trigger(event(), func(e *core.BackupEvent) error { called = true; return nil })
+	if err == nil || called {
+		t.Error("concurrent backup entered snapshot finalizer")
+	}
+	app.OnBackupRestore().BindFunc(func(e *core.BackupEvent) error { called = true; return errors.New("restore reached") })
+	called = false
+	if err = app.OnBackupRestore().Trigger(event()); err == nil || called {
+		t.Error("restore entered while snapshot was active")
+	}
+}

package/backups/register.go

@@ -9,6 +9,7 @@ import (
 	"os"
 	"path/filepath"
 	"strings"
+	"sync"
 	"time"
 )
 
@@ -38,6 +39,16 @@ func (a *stagedApp) NewBackupsFilesystem() (*filesystem.System, error) {
 	return filesystem.NewLocal(a.dir)
 }
 func Register(app core.App, config func(core.App) (Config, error)) {
+	var operation sync.Mutex
+	guard := func(e *core.BackupEvent) error {
+		if !operation.TryLock() {
+			return errors.New("backup/restore operation already running")
+		}
+		defer operation.Unlock()
+		return e.Next()
+	}
+	app.OnBackupCreate().Bind(&hook.Handler[*core.BackupEvent]{Id: "spink.backup.guard", Priority: -2000, Func: guard})
+	app.OnBackupRestore().Bind(&hook.Handler[*core.BackupEvent]{Id: "spink.restore.guard", Priority: -2000, Func: guard})
 	app.OnBackupCreate().BindFunc(func(e *core.BackupEvent) error {
 		c, err := config(e.App)
 		if err != nil {

package/bin/launcher.test.mjs

@@ -0,0 +1,31 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {realpathSync,mkdtempSync,readFileSync,writeFileSync,mkdirSync,rmSync} from 'node:fs';
+import {tmpdir} from 'node:os';
+import {join} from 'node:path';
+import {spawnSync} from 'node:child_process';
+import {fileURLToPath} from 'node:url';
+const cli=fileURLToPath(new URL('./pocketbase-extension.mjs',import.meta.url));
+function fixture(t){const dir=realpathSync(mkdtempSync(join(tmpdir(),'addon-cli-test-')));t.after(()=>rmSync(dir,{recursive:true,force:true}));return dir;}
+test('init creates private configs and preserves operator edits',t=>{
+ const dir=fixture(t);
+ const run=()=>spawnSync(process.execPath,[cli,'init'],{cwd:dir,encoding:'utf8'});
+ assert.equal(run().status,0);
+ assert.deepEqual(JSON.parse(readFileSync(join(dir,'hosting.json'))),{targets:[{key:'native',kind:'native'}]});
+ assert.deepEqual(JSON.parse(readFileSync(join(dir,'gateway.json'))).tenants[0],{host:'localhost:8095',origin:'http://127.0.0.1:8090'});
+ writeFileSync(join(dir,'hosting.json'),'operator config');
+ assert.equal(run().status,0);
+ assert.equal(readFileSync(join(dir,'hosting.json'),'utf8'),'operator config');
+});
+for(const command of ['hosting','gateway','edge','loadtest','import-fork','serve'])test(`launcher dispatches ${command} from caller directory`,t=>{
+ const dir=fixture(t),bin=join(dir,'bin');mkdirSync(bin);
+ writeFileSync(join(bin,'go'),`#!${process.execPath}\nimport fs from 'node:fs';\nconst a=process.argv.slice(2);fs.writeFileSync(process.env.BUILD_LOG,JSON.stringify({args:a,cwd:process.cwd(),gowork:process.env.GOWORK}));fs.writeFileSync(a[a.indexOf('-o')+1],'#!${process.execPath}\\nconsole.log(JSON.stringify({args:process.argv.slice(2),cwd:process.cwd()}))',{mode:0o700});`,{mode:0o700});
+ const result=spawnSync(process.execPath,[cli,command,'--help'],{cwd:dir,encoding:'utf8',env:{...process.env,PATH:bin+':'+process.env.PATH,BUILD_LOG:join(dir,'build.json')}});
+ assert.equal(result.status,0,result.stderr);
+ const build=JSON.parse(readFileSync(join(dir,'build.json')));
+ assert.equal(build.args.at(-1),'./cmd/'+(command==='serve'?'pocketbase':command));
+ assert.equal(build.gowork,'off');
+ const child=JSON.parse(result.stdout);
+ assert.equal(child.cwd,dir);
+ assert.deepEqual(child.args,command==='serve'?['serve','--help','--dir='+join(dir,'pb_data')]:['--help']);
+});

package/bin/pocketbase-extension.mjs

@@ -1,13 +1,27 @@
 #!/usr/bin/env node
 import {spawn,spawnSync} from 'node:child_process';
-import {mkdtempSync,rmSync} from 'node:fs';
+import {mkdtempSync,rmSync,mkdirSync,writeFileSync} from 'node:fs';
 import {tmpdir} from 'node:os';
 import {fileURLToPath} from 'node:url';
 import {resolve,join} from 'node:path';
 const root=fileURLToPath(new URL('..',import.meta.url));
 const args=process.argv.slice(2);
+if(args[0]==='init'){
+ const dir=resolve(process.cwd(),args[1]||'.');
+ mkdirSync(dir,{recursive:true});
+ const files={
+  'hosting.json':JSON.stringify({targets:[{key:'native',kind:'native'}]},null,2)+'\n',
+  'gateway.json':JSON.stringify({allowHTTP:true,tenants:[{host:'localhost:8095',origin:'http://127.0.0.1:8090'}]},null,2)+'\n'
+ };
+ for(const [name,content] of Object.entries(files)){
+  try{writeFileSync(join(dir,name),content,{flag:'wx',mode:0o600});}
+  catch(error){if(error.code!=='EEXIST')throw error;}
+ }
+ console.log('Created missing hosting.json and gateway.json. See the packaged README for startup and private-origin deployment.');
+ process.exit(0);
+}
 let target='pocketbase';
-if(args[0]==='loadtest'||args[0]==='import-fork')target=args.shift();
+if(['loadtest','import-fork','hosting','gateway','edge'].includes(args[0]))target=args.shift();
 if(target==='pocketbase'&&args.length===0)args.push('serve');
 let hasDir=false;
 for(let i=0;i<args.length;i++){
@@ -21,5 +35,5 @@ const result=spawnSync('go',['build','-o',binary,'./cmd/'+target],{cwd:root,stdi
 if(result.error||result.status!==0){rmSync(temp,{recursive:true,force:true});console.error('Building the extension requires Go 1.27+.',result.error?.message||'');process.exit(result.status||1);}
 const child=spawn(binary,args,{cwd:process.cwd(),stdio:'inherit',env:process.env});
 child.on('error',error=>{rmSync(temp,{recursive:true,force:true});console.error(error.message);process.exitCode=1;});
-for(const signal of ['SIGINT','SIGTERM'])process.on(signal,()=>child.kill(signal));
+for(const signal of ['SIGINT','SIGTERM',...(target==='gateway'?['SIGHUP']:[])])process.on(signal,()=>child.kill(signal));
 child.on('exit',(code,signal)=>{rmSync(temp,{recursive:true,force:true});process.exitCode=code??(signal?1:0)});

package/cmd/edge/main.go

@@ -22,6 +22,7 @@ func main() {
 	operator := flag.String("operator", ":8081", "Operator listener; publish on loopback only")
 	policyPath := flag.String("policy", "/etc/spink/edge.json", "Edge policy file")
 	checkpoint := flag.String("checkpoint", "/state/state.json", "Read-only security checkpoint")
+	telemetryPath := flag.String("telemetry", "", "Aggregate telemetry output file; use a separate shared volume")
 	probe := flag.String("probe", "", "Health URL to check and exit")
 	flag.Parse()
 	if *probe != "" {
@@ -54,6 +55,28 @@ func main() {
 	}
 	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
 	defer stop()
+	if *telemetryPath != "" {
+		go func() {
+			tick := time.NewTicker(time.Second)
+			defer tick.Stop()
+			failed := false
+			for {
+				err := g.WriteTelemetry(*telemetryPath)
+				if err != nil && !failed {
+					slog.Error("edge telemetry unavailable", "error", err)
+				}
+				if err == nil && failed {
+					slog.Info("edge telemetry restored")
+				}
+				failed = err != nil
+				select {
+				case <-ctx.Done():
+					return
+				case <-tick.C:
+				}
+			}
+		}()
+	}
 	go func() {
 		ticker := time.NewTicker(time.Second)
 		defer ticker.Stop()
@@ -120,4 +143,9 @@ func main() {
 	for _, s := range servers {
 		s.Shutdown(shutdown)
 	}
+	if *telemetryPath != "" {
+		if err := g.WriteTelemetry(*telemetryPath); err != nil {
+			slog.Error("final telemetry write", "error", err)
+		}
+	}
 }

package/cmd/gateway/main.go

@@ -0,0 +1,84 @@
+package main
+
+import (
+	"context"
+	"flag"
+	gateway "github.com/spink-dev/pocketbase-extension/multinode"
+	"golang.org/x/net/netutil"
+	"log"
+	"net"
+	"net/http"
+	"os"
+	"os/signal"
+	"sync/atomic"
+	"syscall"
+	"time"
+)
+
+func main() {
+	path := flag.String("config", "gateway.json", "routing configuration")
+	addr := flag.String("listen", "127.0.0.1:8095", "listen address")
+	flag.Parse()
+	f, err := os.Open(*path)
+	if err != nil {
+		log.Fatal(err)
+	}
+	config, err := gateway.Load(f)
+	f.Close()
+	if err != nil {
+		log.Fatal(err)
+	}
+	g, err := gateway.New(config)
+	if err != nil {
+		log.Fatal(err)
+	}
+	var current atomic.Pointer[gateway.Gateway]
+	current.Store(g)
+	s := &http.Server{Addr: *addr, Handler: http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { current.Load().ServeHTTP(w, r) }), ReadHeaderTimeout: 5 * time.Second, ReadTimeout: 30 * time.Second, IdleTimeout: 60 * time.Second, MaxHeaderBytes: 32 << 10}
+	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
+	defer stop()
+	reload := make(chan os.Signal, 1)
+	signal.Notify(reload, syscall.SIGHUP)
+	defer signal.Stop(reload)
+	go func() {
+		for {
+			select {
+			case <-ctx.Done():
+				return
+			case <-reload:
+				f, err := os.Open(*path)
+				if err != nil {
+					log.Print("routing reload failed")
+					continue
+				}
+				config, err := gateway.Load(f)
+				f.Close()
+				if err != nil {
+					log.Print("routing reload invalid")
+					continue
+				}
+				next, err := gateway.New(config)
+				if err != nil {
+					log.Print("routing reload invalid")
+					continue
+				}
+				current.Swap(next).CloseIdleConnections()
+				log.Print("routing reloaded")
+			}
+		}
+	}()
+	go func() {
+		<-ctx.Done()
+		shutdown, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+		defer cancel()
+		s.Shutdown(shutdown)
+	}()
+	log.Printf("gateway listening on %s", *addr)
+	listener, err := net.Listen("tcp", *addr)
+	if err != nil {
+		log.Fatal(err)
+	}
+	if err = s.Serve(netutil.LimitListener(listener, 512)); err != nil && err != http.ErrServerClosed {
+		log.Fatal(err)
+	}
+}