signalk-backup 0.5.0 → 0.6.1

package/README.md

@@ -1,16 +1,18 @@
 # signalk-backup
 
-Scheduled deduplicated backups of your SignalK config (and optionally history) to local storage and Google Drive.
+Scheduled deduplicated backups of your SignalK config (and optionally history) to local storage, USB / NAS, or Google Drive — with a tree-browser that lets you restore individual files from any snapshot, anywhere your user can write.
 
-The plugin is a thin shell: it asks [signalk-container](https://github.com/dirkwa/signalk-container) to run the backup engine in a container ([signalk-backup-server](https://github.com/dirkwa/signalk-backup-server)) and presents a redirect to the engine's UI as a SignalK webapp. All backup work — Kopia snapshots, rclone Google Drive sync, scheduling, restore-with-rollback — happens inside the container.
+The plugin runs a React webapp inside the SignalK Admin UI and orchestrates a separate backup-engine container ([signalk-backup-server](https://github.com/dirkwa/signalk-backup-server)). All Kopia snapshot work happens in the container; the plugin handles the UI, the database-export tick, and host-side file writes for restores that target paths the container can't see.
 
 ## Features
 
 - **Content-addressable deduplication** — Kopia stores file blobs once across all snapshots; identical config files between hourly/daily/weekly retention tiers cost nothing
-- **Cloud sync to Google Drive** — optional, opt-in. Uses rclone with `drive.file` scope (the app only sees files it created)
 - **Scheduled backups** — hourly / daily / weekly / on-startup tiers, each with independent retention
-- **Restore with safety backup** — every restore creates a snapshot of the current state first, so a botched restore can be rolled back automatically
-- **Database export pipeline** — opt-in exporters for [signalk-questdb](https://github.com/dirkwa/signalk-questdb), [signalk-grafana](https://github.com/dirkwa/signalk-grafana), and [signalk-database](https://github.com/dirkwa/signalk-database) periodically write consistent snapshots (parquet, SQLite checkpoint, provisioning YAML) to a staging dir that kopia includes in every snapshot. Live DB files are excluded from filesystem-level backup to avoid torn-write hazards; the export side is how DB state actually gets backed up. Manual backups run pending exports synchronously first.
+- **Cloud + local destinations** — Google Drive (rclone, `drive.file` scope, opt-in OAuth), USB / NAS via local-fs, or SMB share. Snapshots stay in the local Kopia repo even when cloud sync is configured
+- **Selective restore** — browse any backup's file tree, download a single file or whole subdirectory, or restore in-place. The trailing slash on a custom path means "land inside as a directory", so `tmp/` plus a file source writes `tmp/<filename>` instead of overwriting `tmp` as a file
+- **Restore-anywhere** — custom-path restores stream through the plugin and write under the SignalK user's permissions, so you can land restored bytes in `/tmp`, `/media/usb/...`, or your home directory — anywhere your user can write
+- **Restore with safety backup** — every full restore creates a snapshot of the current state first; partial restores stash the existing target as a sibling before overwriting. Both flows can be rolled back automatically on failure
+- **Database export pipeline** — opt-in exporters for [signalk-questdb](https://github.com/dirkwa/signalk-questdb), [signalk-grafana](https://github.com/dirkwa/signalk-grafana), and [signalk-database](https://github.com/dirkwa/signalk-database) periodically write consistent snapshots (parquet, SQLite checkpoint, provisioning YAML) to a staging dir that Kopia includes in every snapshot. Live DB files are excluded from filesystem backup to avoid torn-write hazards. The dedicated "Database exports" tab also extracts the export subtree from any historical backup without pulling the whole snapshot — a direct answer to "QuestDB shards bloat the full zip"
 - **First-run safe default** — installs with a daily local-only schedule already seeded; no surprise data egress
 - **Update detection** — checks ghcr.io for new container images via signalk-container's centralized update service
 
@@ -18,7 +20,7 @@ The plugin is a thin shell: it asks [signalk-container](https://github.com/dirkw
 
 - SignalK Server ≥ 2.24.0
 - Node 22 or newer (24 recommended)
-- [signalk-container](https://github.com/dirkwa/signalk-container) ≥ 0.1.6 (provides the container runtime)
+- [signalk-container](https://github.com/dirkwa/signalk-container) ≥ 1.6.0 (provides the container runtime)
 - Podman or Docker on the host
 
 ## Install
@@ -28,38 +30,44 @@ The plugin is a thin shell: it asks [signalk-container](https://github.com/dirkw
 # (auto-enables on install — first-run schedules a daily local backup)
 ```
 
-The plugin pulls `ghcr.io/dirkwa/signalk-backup-server:latest` on first run. The container is small (~80 MB compressed). Subsequent updates are detected and surfaced in the signalk-container config panel.
+The plugin pulls `ghcr.io/dirkwa/signalk-backup-server` at a server version it pins itself (see [src/config/image-tag.ts](src/config/image-tag.ts)). Plugin releases and server releases are decoupled — you can pin or float either independently via the plugin's `imageTag` setting.
 
 ## How it works
 
-```
-Your browser
-  └── /plugins/signalk-backup/                 ← redirect HTML
-       └── plugin proxies /api/gui-url
-            └── backup-server container UI
-                 (snapshots, restore wizard, cloud sync, settings)
+```text
+Browser
+  └── /signalk-backup/                                  ← plugin webapp (React)
+       └── /plugins/signalk-backup/api/*                ← plugin's reverse proxy
+            ├── /api/db-export/staging                  ← plugin-local (file lister)
+            ├── /api/restore-partial-host               ← plugin-local (writes to host fs)
+            └── /api/backups/*, /api/cloud/*, …         ← proxied to backup-server container
+                 └── http://127.0.0.1:<port>/api/*
+                      (Kopia snapshots, restore-with-rollback,
+                       partial-restore state machine, cloud sync)
 ```
 
-When you visit `/plugins/signalk-backup/` in the SignalK Admin UI, the plugin's redirect HTML asks `/plugins/signalk-backup/api/gui-url` for the current backup-server location and bounces your browser there. This means the UI version is always in sync with the running container.
+The plugin is most of the user experience:
 
-## Configuration
+- The **webapp** at `/signalk-backup/` is a React SPA bundled by Vite. It runs in the SignalK admin origin and reads/writes via `fetch('/plugins/signalk-backup/api/*')`. No CORS dance, no separate auth — it inherits SignalK's.
+- The **plugin process** owns three things directly: the database-export scheduler tick, an HTTP route that lists / streams files from the staging tree (so the webapp can show "live" exports), and an HTTP route that performs host-side file writes for custom-path restores.
+- Everything else — Kopia snapshots, restore-with-rollback, cloud sync, scheduling — runs in the [signalk-backup-server](https://github.com/dirkwa/signalk-backup-server) container. The plugin reverse-proxies `/api/*` through to it, and adds a small set of explicit overrides above the catch-all proxy.
 
-Most configuration lives in the **Backup Console** (open it from the redirect, or from the SignalK Admin UI plugin config: "Open Backup Console"). The Console handles:
+The webapp has four tabs:
 
-- Backup schedule (hourly / daily / weekly / startup) and retention tiers
-- Backup excludes (paths to skip — default: `node_modules/`, `charts*/`)
-- Repository password (Kopia encryption key)
-- Cloud sync mode (off / manual / daily / weekly)
-- Google Drive connection (one-click OAuth via `rclone authorize drive`)
-- Database export toggles (QuestDB, Grafana, signalk-database) and export interval
-- Snapshot browser, restore wizard
+- **Dashboard** — status, recent backups, scheduler next-run times
+- **Backups** — create, list, download, restore (full or selective), upload a ZIP, delete
+- **Database exports** — live staging table (one row per exporter file currently on disk) plus a "pick a backup → browse the database-exports subtree" extractor for grabbing historical shards without pulling the whole snapshot
+- **Cloud sync** — provider chooser (Google Drive / local / SMB), credentials, sync mode, on-demand sync
+
+## Configuration
 
-The SignalK Admin UI plugin panel (small) handles only deployment-level settings:
+Most settings live in the **webapp** under Settings. The plugin's SignalK Admin UI config panel is intentionally small and handles only deployment-level options (the schema in [src/config/schema.ts](src/config/schema.ts) is the source of truth — update this list if you bump it):
 
-- `managedContainer` — whether to manage the container yourself or point at an external backup-server
-- `imageTag` — pin a specific version or use a floating tag like `latest`
+- `managedContainer` — let the plugin manage the backup-server container (default), or point at an external instance
+- `imageTag` — pin a specific version or use `auto` (default — resolves to the BACKUP_SERVER_VERSION constant)
 - `externalUrl` — only used when `managedContainer: false`
-- `logLevel` — forwarded to the container
+- `databaseExport.{questdb, grafana, signalkDatabase}` — enable per-exporter (default off; users opt in once their DB plugin is producing data)
+- `databaseExport.intervalMinutes` — how often the export tick runs (5–1440)
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "signalk-backup",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "Scheduled deduplicated backups of SignalK config to local storage and Google Drive (via Kopia + rclone)",
   "main": "plugin/index.js",
   "type": "module",
@@ -33,6 +33,14 @@
       "name": "Backup",
       "description": "Scheduled deduplicated backups to local storage and Google Drive"
     },
+    "screenshots": [
+      "./docs/screenshots/1_signalk-backup_dashboard.png",
+      "./docs/screenshots/2_signalk-backup_backups.png",
+      "./docs/screenshots/3_signalk-backup_browse.png",
+      "./docs/screenshots/4_signalk-backup_database-exports.png",
+      "./docs/screenshots/5_signalk-backup_cloud-sync.png",
+      "./docs/screenshots/6_signalk-backup_settings.png"
+    ],
     "requires": [
       "signalk-container"
     ]
@@ -49,7 +57,8 @@
   },
   "dependencies": {
     "@sinclair/typebox": "^0.34.0",
-    "bonjour-service": "^1.3.0"
+    "bonjour-service": "^1.3.0",
+    "unzipper": "^0.12.3"
   },
   "peerDependencies": {
     "signalk-container": ">=1.6.0"
@@ -68,6 +77,7 @@
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "@types/supertest": "^7.2.0",
+    "@types/unzipper": "^0.10.11",
     "@vitejs/plugin-react": "^6.0.1",
     "bootstrap": "^5.3.8",
     "eslint": "^10.3.0",

package/plugin/config/image-tag.d.ts

@@ -1,3 +1,3 @@
-export declare const PLUGIN_VERSION: string;
+export declare const BACKUP_SERVER_VERSION = "0.5.0";
 export declare function resolveImageTag(tag: string): string;
 //# sourceMappingURL=image-tag.d.ts.map

package/plugin/config/image-tag.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"image-tag.d.ts","sourceRoot":"","sources":["../../src/config/image-tag.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,cAAc,QAOvB,CAAA;AAGJ,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEnD"}
+{"version":3,"file":"image-tag.d.ts","sourceRoot":"","sources":["../../src/config/image-tag.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,qBAAqB,UAAU,CAAA;AAE5C,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEnD"}

package/plugin/config/image-tag.js

@@ -1,16 +1,9 @@
-import { readFileSync } from 'node:fs';
-import { fileURLToPath } from 'node:url';
-// CI publishes signalk-backup-server:X.Y.Z in lockstep with this plugin's package.json version.
-export const PLUGIN_VERSION = (() => {
-    const pkgPath = fileURLToPath(new URL('../../package.json', import.meta.url));
-    const raw = JSON.parse(readFileSync(pkgPath, 'utf-8'));
-    if (typeof raw.version !== 'string') {
-        throw new Error('signalk-backup package.json has no version field');
-    }
-    return raw.version;
-})();
-// 'auto' resolves to PLUGIN_VERSION so the container tracks plugin upgrades; other tags pass through.
+// The signalk-backup-server image version that "auto" resolves to.
+// Bump this when a new signalk-backup-server release is published to ghcr.io.
+// Independent of signalk-backup's own package.json version — the two repos
+// release on independent cadences. See AGENTS.md "Gotchas" for rationale.
+export const BACKUP_SERVER_VERSION = '0.5.0';
 export function resolveImageTag(tag) {
-    return tag === 'auto' ? PLUGIN_VERSION : tag;
+    return tag === 'auto' ? BACKUP_SERVER_VERSION : tag;
 }
 //# sourceMappingURL=image-tag.js.map

package/plugin/config/image-tag.js.map

@@ -1 +1 @@
-{"version":3,"file":"image-tag.js","sourceRoot":"","sources":["../../src/config/image-tag.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AACtC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAExC,gGAAgG;AAChG,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,GAAG,EAAE;IAClC,MAAM,OAAO,GAAG,aAAa,CAAC,IAAI,GAAG,CAAC,oBAAoB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAA;IAC7E,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,CAA0B,CAAA;IAC/E,IAAI,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;QACpC,MAAM,IAAI,KAAK,CAAC,kDAAkD,CAAC,CAAA;IACrE,CAAC;IACD,OAAO,GAAG,CAAC,OAAO,CAAA;AACpB,CAAC,CAAC,EAAE,CAAA;AAEJ,sGAAsG;AACtG,MAAM,UAAU,eAAe,CAAC,GAAW;IACzC,OAAO,GAAG,KAAK,MAAM,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,GAAG,CAAA;AAC9C,CAAC"}
+{"version":3,"file":"image-tag.js","sourceRoot":"","sources":["../../src/config/image-tag.ts"],"names":[],"mappings":"AAAA,mEAAmE;AACnE,8EAA8E;AAC9E,2EAA2E;AAC3E,0EAA0E;AAC1E,MAAM,CAAC,MAAM,qBAAqB,GAAG,OAAO,CAAA;AAE5C,MAAM,UAAU,eAAe,CAAC,GAAW;IACzC,OAAO,GAAG,KAAK,MAAM,CAAC,CAAC,CAAC,qBAAqB,CAAC,CAAC,CAAC,GAAG,CAAA;AACrD,CAAC"}

package/plugin/config/schema.js

@@ -19,7 +19,7 @@ export const ConfigSchema = Type.Object({
     imageTag: Type.String({
         default: 'auto',
         title: 'Container image tag',
-        description: '"auto" (default) tracks the plugin version, so upgrading the plugin upgrades the container. ' +
+        description: '"auto" (default) tracks the signalk-backup-server version this plugin release was tested against. ' +
             'Pin to a specific version (e.g. "0.4.0") or use a floating tag (e.g. "latest") to override.'
     }),
     externalUrl: Type.String({

package/plugin/config/schema.js.map

@@ -1 +1 @@
-{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/config/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAU,MAAM,mBAAmB,CAAA;AAEhD;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,IAAI,CAAC,MAAM,CAAC;IACtC,gBAAgB,EAAE,IAAI,CAAC,OAAO,CAAC;QAC7B,OAAO,EAAE,IAAI;QACb,KAAK,EAAE,+CAA+C;QACtD,WAAW,EACT,0FAA0F;YAC1F,4EAA4E;KAC/E,CAAC;IACF,QAAQ,EAAE,IAAI,CAAC,MAAM,CAAC;QACpB,OAAO,EAAE,MAAM;QACf,KAAK,EAAE,qBAAqB;QAC5B,WAAW,EACT,8FAA8F;YAC9F,6FAA6F;KAChG,CAAC;IACF,WAAW,EAAE,IAAI,CAAC,MAAM,CAAC;QACvB,OAAO,EAAE,EAAE;QACX,KAAK,EAAE,4BAA4B;QACnC,WAAW,EACT,8EAA8E;YAC9E,0CAA0C;KAC7C,CAAC;IACF,oEAAoE;IACpE,mEAAmE;IACnE,cAAc,EAAE,IAAI,CAAC,MAAM,CACzB;QACE,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;QACzC,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;QACzC,eAAe,EAAE,IAAI,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;QACjD,eAAe,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;KACzE,EACD;QACE,OAAO,EAAE;YACP,OAAO,EAAE,KAAK;YACd,OAAO,EAAE,KAAK;YACd,eAAe,EAAE,KAAK;YACtB,eAAe,EAAE,EAAE;SACpB;KACF,CACF;CACF,CAAC,CAAA;AAIF;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,eAAe,GAAW;IACrC,gBAAgB,EAAE,IAAI;IACtB,QAAQ,EAAE,MAAM;IAChB,WAAW,EAAE,EAAE;IACf,cAAc,EAAE;QACd,OAAO,EAAE,KAAK;QACd,OAAO,EAAE,KAAK;QACd,eAAe,EAAE,KAAK;QACtB,eAAe,EAAE,EAAE;KACpB;CACF,CAAA"}
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/config/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAU,MAAM,mBAAmB,CAAA;AAEhD;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,IAAI,CAAC,MAAM,CAAC;IACtC,gBAAgB,EAAE,IAAI,CAAC,OAAO,CAAC;QAC7B,OAAO,EAAE,IAAI;QACb,KAAK,EAAE,+CAA+C;QACtD,WAAW,EACT,0FAA0F;YAC1F,4EAA4E;KAC/E,CAAC;IACF,QAAQ,EAAE,IAAI,CAAC,MAAM,CAAC;QACpB,OAAO,EAAE,MAAM;QACf,KAAK,EAAE,qBAAqB;QAC5B,WAAW,EACT,oGAAoG;YACpG,6FAA6F;KAChG,CAAC;IACF,WAAW,EAAE,IAAI,CAAC,MAAM,CAAC;QACvB,OAAO,EAAE,EAAE;QACX,KAAK,EAAE,4BAA4B;QACnC,WAAW,EACT,8EAA8E;YAC9E,0CAA0C;KAC7C,CAAC;IACF,oEAAoE;IACpE,mEAAmE;IACnE,cAAc,EAAE,IAAI,CAAC,MAAM,CACzB;QACE,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;QACzC,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;QACzC,eAAe,EAAE,IAAI,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;QACjD,eAAe,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;KACzE,EACD;QACE,OAAO,EAAE;YACP,OAAO,EAAE,KAAK;YACd,OAAO,EAAE,KAAK;YACd,eAAe,EAAE,KAAK;YACtB,eAAe,EAAE,EAAE;SACpB;KACF,CACF;CACF,CAAC,CAAA;AAIF;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,eAAe,GAAW;IACrC,gBAAgB,EAAE,IAAI;IACtB,QAAQ,EAAE,MAAM;IAChB,WAAW,EAAE,EAAE;IACf,cAAc,EAAE;QACd,OAAO,EAAE,KAAK;QACd,OAAO,EAAE,KAAK;QACd,eAAe,EAAE,KAAK;QACtB,eAAe,EAAE,EAAE;KACpB;CACF,CAAA"}

package/plugin/database-export/staging-routes.d.ts

@@ -0,0 +1,19 @@
+import type { IRouter } from 'express';
+export interface StagingEntry {
+    path: string;
+    size: number;
+    mtime: string;
+}
+export interface StagingRoutesOptions {
+    getStagingRoot: () => string;
+    log?: (msg: string) => void;
+}
+export declare function registerStagingRoutes(router: IRouter, opts: StagingRoutesOptions): void;
+export declare function listStagingFiles(stagingRoot: string): Promise<StagingEntry[]>;
+export declare class StagingPathError extends Error {
+    readonly code: 'INVALID_FILE' | 'OUTSIDE_ROOT';
+    readonly status: number;
+    constructor(message: string, code: 'INVALID_FILE' | 'OUTSIDE_ROOT', status: number);
+}
+export declare function resolveStagingFile(stagingRoot: string, file: string): Promise<string>;
+//# sourceMappingURL=staging-routes.d.ts.map

package/plugin/database-export/staging-routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"staging-routes.d.ts","sourceRoot":"","sources":["../../src/database-export/staging-routes.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,OAAO,EAAqB,MAAM,SAAS,CAAA;AAEzD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,oBAAoB;IACnC,cAAc,EAAE,MAAM,MAAM,CAAA;IAC5B,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;CAC5B;AAGD,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,oBAAoB,GAAG,IAAI,CAyGvF;AAID,wBAAsB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAMnF;AA8BD,qBAAa,gBAAiB,SAAQ,KAAK;aAGvB,IAAI,EAAE,cAAc,GAAG,cAAc;aACrC,MAAM,EAAE,MAAM;gBAF9B,OAAO,EAAE,MAAM,EACC,IAAI,EAAE,cAAc,GAAG,cAAc,EACrC,MAAM,EAAE,MAAM;CAKjC;AAID,wBAAsB,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CA+B3F"}

package/plugin/database-export/staging-routes.js

@@ -0,0 +1,205 @@
+// stagingRoot is hard-pinned by the caller; the file query param is
+// realpath-resolved against it so a manipulated request can't escape.
+import { createReadStream } from 'node:fs';
+import { lstat, readdir, realpath, stat } from 'node:fs/promises';
+import path from 'node:path';
+// Must register before /api/* proxy catch-all to avoid forwarding to backup-server.
+export function registerStagingRoutes(router, opts) {
+    router.get('/api/db-export/staging', async (_req, res) => {
+        const root = opts.getStagingRoot();
+        try {
+            const entries = await listStagingFiles(root);
+            res.json({
+                success: true,
+                data: { stagingRoot: root, entries },
+                timestamp: new Date().toISOString()
+            });
+        }
+        catch (err) {
+            opts.log?.(`staging list failed: ${errMsg(err)}`);
+            if (isENOENT(err)) {
+                res.json({
+                    success: true,
+                    data: { stagingRoot: root, entries: [] },
+                    timestamp: new Date().toISOString()
+                });
+                return;
+            }
+            res.status(500).json({
+                success: false,
+                error: { code: 'STAGING_LIST_FAILED', message: errMsg(err) },
+                timestamp: new Date().toISOString()
+            });
+        }
+    });
+    router.get('/api/db-export/staging/download', async (req, res) => {
+        const fileParam = typeof req.query.file === 'string' ? req.query.file : '';
+        if (!fileParam) {
+            res.status(400).json({
+                success: false,
+                error: {
+                    code: 'INVALID_INPUT',
+                    message: 'file query parameter is required'
+                },
+                timestamp: new Date().toISOString()
+            });
+            return;
+        }
+        const root = opts.getStagingRoot();
+        let absoluteFile;
+        try {
+            absoluteFile = await resolveStagingFile(root, fileParam);
+        }
+        catch (err) {
+            const status = err instanceof StagingPathError ? err.status : 500;
+            res.status(status).json({
+                success: false,
+                error: {
+                    code: err instanceof StagingPathError ? err.code : 'INTERNAL',
+                    message: errMsg(err)
+                },
+                timestamp: new Date().toISOString()
+            });
+            return;
+        }
+        // Stat is the final gate: if the resolved path is a directory we
+        // refuse — directory downloads go through the server's zip-subtree
+        // endpoint, not here.
+        let s;
+        try {
+            s = await stat(absoluteFile);
+        }
+        catch (err) {
+            const status = isENOENT(err) ? 404 : 500;
+            res.status(status).json({
+                success: false,
+                error: {
+                    code: status === 404 ? 'FILE_NOT_FOUND' : 'STAT_FAILED',
+                    message: errMsg(err)
+                },
+                timestamp: new Date().toISOString()
+            });
+            return;
+        }
+        if (!s.isFile()) {
+            res.status(400).json({
+                success: false,
+                error: {
+                    code: 'NOT_A_FILE',
+                    message: 'staging download only serves regular files; use the snapshot subtree endpoint for directories'
+                },
+                timestamp: new Date().toISOString()
+            });
+            return;
+        }
+        const safeName = path.basename(fileParam).replace(/[^A-Za-z0-9._-]/g, '_') || 'staging-file';
+        res.setHeader('Content-Type', 'application/octet-stream');
+        res.setHeader('Content-Disposition', `attachment; filename="${safeName}"`);
+        res.setHeader('Content-Length', String(s.size));
+        const stream = createReadStream(absoluteFile);
+        stream.on('error', (err) => {
+            opts.log?.(`staging stream error for ${absoluteFile}: ${errMsg(err)}`);
+            if (!res.headersSent) {
+                res.status(500).end();
+            }
+            else {
+                res.end();
+            }
+        });
+        stream.pipe(res);
+    });
+}
+// Recursively lists regular files under stagingRoot; throws ENOENT if
+// root is missing (route handler maps that to an empty response).
+export async function listStagingFiles(stagingRoot) {
+    const root = await realpath(stagingRoot);
+    const out = [];
+    await walk(root, root, out);
+    out.sort((a, b) => a.path.localeCompare(b.path));
+    return out;
+}
+async function walk(root, current, out) {
+    let entries;
+    try {
+        entries = await readdir(current, { withFileTypes: true });
+    }
+    catch (err) {
+        if (isENOENT(err))
+            return;
+        throw err;
+    }
+    for (const entry of entries) {
+        const child = path.join(current, entry.name);
+        if (entry.isDirectory()) {
+            await walk(root, child, out);
+            continue;
+        }
+        if (!entry.isFile())
+            continue;
+        // lstat (not stat) so a symlink swapped in between readdir and here
+        // doesn't get followed; re-verify isFile after the lstat in case the
+        // entry was replaced.
+        const s = await lstat(child);
+        if (!s.isFile())
+            continue;
+        out.push({
+            path: path.relative(root, child).split(path.sep).join('/'),
+            size: s.size,
+            mtime: s.mtime.toISOString()
+        });
+    }
+}
+export class StagingPathError extends Error {
+    code;
+    status;
+    constructor(message, code, status) {
+        super(message);
+        this.code = code;
+        this.status = status;
+        this.name = 'StagingPathError';
+    }
+}
+// Realpath both ends so a symlink-hop in the middle is resolved before
+// we compare paths — otherwise a symlink could escape stagingRoot.
+export async function resolveStagingFile(stagingRoot, file) {
+    if (file.includes('\0')) {
+        throw new StagingPathError('file must not contain NUL bytes', 'INVALID_FILE', 400);
+    }
+    if (path.isAbsolute(file)) {
+        throw new StagingPathError('file must be a relative path under the staging root', 'INVALID_FILE', 400);
+    }
+    // Normalize separators so callers can pass forward-slash paths on Windows too.
+    const normalized = file.split(/[/\\]/).filter((p) => p.length > 0);
+    if (normalized.some((p) => p === '..')) {
+        throw new StagingPathError('file must not contain ".." segments', 'INVALID_FILE', 400);
+    }
+    const root = await realpath(stagingRoot);
+    const joined = path.join(root, ...normalized);
+    // Walk up until we find an ancestor that exists; realpath that so a
+    // symlink hop in the middle of the path is resolved before the check.
+    const resolvedAncestor = await resolveExistingAncestor(joined);
+    const rel = path.relative(root, resolvedAncestor);
+    if (rel.startsWith('..') || path.isAbsolute(rel)) {
+        throw new StagingPathError(`file ${file} resolves outside the staging root`, 'OUTSIDE_ROOT', 403);
+    }
+    return joined;
+}
+async function resolveExistingAncestor(target) {
+    let current = target;
+    while (current !== path.dirname(current)) {
+        try {
+            return await realpath(current);
+        }
+        catch {
+            current = path.dirname(current);
+        }
+    }
+    return await realpath(current);
+}
+function isENOENT(err) {
+    return typeof err === 'object' && err !== null && err.code === 'ENOENT';
+}
+function errMsg(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+//# sourceMappingURL=staging-routes.js.map

package/plugin/database-export/staging-routes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"staging-routes.js","sourceRoot":"","sources":["../../src/database-export/staging-routes.ts"],"names":[],"mappings":"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"}

package/plugin/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAA;AAK5C,OAAO,EACL,eAAe,EAKhB,MAAM,YAAY,CAAA;AA2GnB,MAAM,CAAC,OAAO,WAAW,GAAG,EAAE,eAAe,GAAG,MAAM,CA+mBrD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAA;AAK5C,OAAO,EACL,eAAe,EAKhB,MAAM,YAAY,CAAA;AA6GnB,MAAM,CAAC,OAAO,WAAW,GAAG,EAAE,eAAe,GAAG,MAAM,CA8oBrD"}

package/plugin/index.js

@@ -6,6 +6,8 @@ import { discoverSmbHosts, shutdownSmbDiscovery } from './smb-discovery.js';
 import { ConfigSchema, SCHEMA_DEFAULTS } from './config/schema.js';
 import { resolveImageTag } from './config/image-tag.js';
 import { runAllExports } from './database-export/index.js';
+import { registerStagingRoutes } from './database-export/staging-routes.js';
+import { registerHostRestoreRoutes } from './restore-host-write.js';
 const BACKUP_IMAGE = 'ghcr.io/dirkwa/signalk-backup-server';
 const CONTAINER_NAME = 'signalk-backup-server';
 const PLUGIN_ID = 'signalk-backup';
@@ -246,13 +248,19 @@ export default function (app) {
                 if (!containerImage) {
                     containerImage = `${BACKUP_IMAGE}:${resolveImageTag(currentSettings?.imageTag ?? 'auto')}`;
                 }
+                // pathMapping: translate backup-server container paths back to host paths for restore banners.
+                const managed = currentSettings?.managedContainer !== false;
+                const pathMapping = managed
+                    ? { containerPath: SK_MOUNT, hostPath: resolveSignalkConfigRoot() }
+                    : undefined;
                 res.json({
                     container: {
                         state: containerState,
                         image: containerImage,
-                        managed: currentSettings?.managedContainer !== false
+                        managed
                     },
-                    ready: client !== null
+                    ready: client !== null,
+                    ...(pathMapping ? { pathMapping } : {})
                 });
             });
             // Update detection — delegated to signalk-container's centralized
@@ -408,6 +416,28 @@ export default function (app) {
                 startDbExportTimer();
                 res.json({ success: true, data: next, timestamp: new Date().toISOString() });
             });
+            // Live staging tree — files the plugin's own db-export tick wrote
+            // to <getDataDirPath()>/database-exports/<sourcePluginId>/. The
+            // root is hard-pinned here; the route handlers refuse anything
+            // that resolves outside it. Snapshotted shards (from older
+            // backups) go through the backup-server's /download-subtree.
+            registerStagingRoutes(router, {
+                getStagingRoot: () => path.join(app.getDataDirPath(), 'database-exports'),
+                log: (msg) => {
+                    app.debug(msg);
+                }
+            });
+            // Host-side restore for "Custom path" targets — bypasses the
+            // backup-server container's filesystem so the user can land
+            // restored files anywhere the SignalK process can write.
+            // Original-location restores still go through the proxy to the
+            // server's restore-partial route.
+            registerHostRestoreRoutes(router, {
+                getUpstreamBase: () => containerAddress,
+                log: (msg) => {
+                    app.debug(msg);
+                }
+            });
             // Discovery runs here, not in the container, so multicast doesn't
             // have to traverse the backup-server's network namespace.
             router.get('/api/cloud/smb/discover', async (_req, res) => {