Phase 2: disaster recovery (occ backup:restore:full)

New commands, per PLAN.md 3.7:
- occ backup:key:import: adopt the master key from a recovery kit on a fresh installation
  (instead of occ backup:key:init generating a new one), so occ backup:target:add opens the
  existing repository on the location rather than creating an empty one.
- occ backup:restore:full: replace the database (consistent, one transaction), restore the data
  directory in place, and merge config.php -- refuses up front and lists what's missing when the
  Nextcloud major version or any app enabled at backup time doesn't match here (their tables must
  exist before the database restore can use them), rather than guessing or partially applying.

Repository::restore() gained an optional $stripPrefix (write "data/<uid>/..." straight into the
real data directory, not a "data/" subdirectory of it) -- restoring "data/" and "config/" this way
needs no temporary copy of what can be the largest part of an instance.

occ backup:target:add now backfills the local snapshot cache (ngb_snapshots, what occ backup:list
actually reads) when it adopts an existing repository: without this, a freshly connected location
showed no restore points at all, even though the repository itself had them. One unreadable
snapshot is skipped rather than aborting the backfill or the target add itself.

Three self-referential problems found and fixed by testing this against two real, separate
Nextcloud instances sharing only the backup location (tests/integration/full-restore-roundtrip.sh
covers this; the per-process nature of these bugs meant they were invisible from inside a single
occ invocation, including the one used to write the fixes, which is exactly why a second, fresh
process re-running occ backup:status etc. was necessary to catch them):
- The full database dump includes ng_backup's own tables and appconfig rows; restoring them
  verbatim would overwrite the key/target that is actively performing the restore, on THIS
  installation, with the backed-up instance's. Both are now preserved: ng_backup's own tables
  (and, on PostgreSQL, their sequences -- excluding a table does not exclude its sequence) are
  excluded from what gets restored, and its appconfig rows are captured before the database
  restore and written back after, in their own transaction.
- config.php's 'secret' is merged in from the backup (needed so already-encrypted content in the
  restored database, e.g. share tokens, stays decryptable), but Target::options, the master key,
  the wrapped key and the recovery kit code are all encrypted with that same instance secret
  (OCP's ICrypto, or Nextcloud AppConfig's own "sensitive" flag underneath), not with ng_backup's
  own key. Changing it without re-encrypting them first left all four permanently undecryptable
  the moment any later occ command ran. Fixed with two helpers
  (TargetService::reencryptOptionsAround(), KeyService::reencryptForSecretRotation()) that decrypt
  before and re-encrypt after whatever callback actually changes the secret; config.php is applied
  dead last in restoreFull(), after every other repository access. Not crash-safe (a process kill
  mid-rotation would leave a key missing, not just stale) -- disaster recovery is run once by
  hand, right after occ maintenance:install, a window too narrow yet to justify a two-phase write.
- A subtler variant of the same bug: Nextcloud's own AppConfig additionally encrypts a "sensitive"
  value itself, tied to the same secret, underneath our own encryption. Overwriting an existing
  sensitive key makes it read the old value first to compare, which then also fails against the
  new secret. Deleting the key before setting the new value avoids that read entirely.

Roadmap (PLAN.md 9): phase 3 (in-place full restore, user self-service) moved out to v1.3.0; phase
2 continues toward v1.2.0 with FTP/SMB, a verification/checksum-audit command, user-export
retention, and deciding whether per-user export joins the automatic schedule.

tests/integration/full-restore-roundtrip.sh

@@ -0,0 +1,86 @@
+#!/bin/bash
+# Disaster recovery: occ backup:key:import + backup:target:add + backup:restore:full on a
+# SECOND, fresh Nextcloud instance that never saw the first one, sharing only the backup
+# location (a local directory, bind-mounted into both containers) -- see PLAN.md 3.7.
+# Usage: full-restore-roundtrip.sh <nextcloud-image-tag>
+#   e.g. full-restore-roundtrip.sh 35-apache
+set -euo pipefail
+IMAGE="nextcloud:${1:-35-apache}"
+APP=$(cd "$(dirname "$0")/../.." && pwd)
+NET=ngb-frt-net
+SHARED=$(mktemp -d)
+chmod 777 "$SHARED"
+fail() { echo "FAIL: $*"; exit 1; }
+ok() { echo "ok   $*"; }
+
+cleanup() {
+	docker rm -fv ngb-frt-origin ngb-frt-restore >/dev/null 2>&1 || true
+	docker network rm "$NET" >/dev/null 2>&1 || true
+	docker run --rm -v "$SHARED:/target" alpine sh -c 'rm -rf /target/*' >/dev/null 2>&1 || true
+	rmdir "$SHARED" 2>/dev/null || true
+	rm -f /tmp/ngb-frt-kit.json /tmp/ngb-frt-pass
+}
+trap cleanup EXIT
+
+run_on() { docker exec -u www-data "$1" php occ "${@:2}"; }
+
+docker network create "$NET" >/dev/null
+docker run -d --name ngb-frt-origin --network "$NET" -e SQLITE_DATABASE=nextcloud \
+	-e NEXTCLOUD_ADMIN_USER=admin -e NEXTCLOUD_ADMIN_PASSWORD=admin \
+	-v "$APP:/var/www/html/custom_apps/ng_backup:ro" -v "$SHARED:/mnt/shared" "$IMAGE" >/dev/null
+for i in $(seq 1 90); do run_on ngb-frt-origin status 2>/dev/null | grep -q "installed: true" && break; sleep 3; done
+docker exec ngb-frt-origin chown www-data:www-data /var/www/html/custom_apps
+run_on ngb-frt-origin app:enable ng_backup >/dev/null
+ok "origin instance up"
+
+docker exec ngb-frt-origin sh -c "printf 'full restore roundtrip passphrase 2026\n' > /tmp/pass"
+run_on ngb-frt-origin backup:key:init --passphrase-file=/tmp/pass --label=CI >/dev/null || fail "key init"
+run_on ngb-frt-origin backup:key:kit --output=/tmp/kit.json >/dev/null
+CODE=$(run_on ngb-frt-origin backup:key:kit | php -r 'echo json_decode(stream_get_contents(STDIN), true)["confirmation_code"];')
+run_on ngb-frt-origin backup:key:confirm -u admin --code="$CODE" --confirm="Yes, I confirm" >/dev/null || fail "confirm"
+run_on ngb-frt-origin backup:target:add offsite local -a null::null -o datadir=/mnt/shared --path=repo >/dev/null || fail "target add"
+ok "key, kit and location on the origin"
+
+NC_PASS=$(openssl rand -hex 16)
+docker exec -u www-data -e OC_PASS="$NC_PASS" ngb-frt-origin php occ user:add --password-from-env frtest >/dev/null
+docker exec ngb-frt-origin sh -c "mkdir -p /var/www/html/data/frtest/files/Docs && head -c 200000 /dev/urandom > /var/www/html/data/frtest/files/Docs/report.bin && echo 'hello disaster recovery' > /var/www/html/data/frtest/files/Docs/note.txt && chown -R www-data:www-data /var/www/html/data/frtest"
+run_on ngb-frt-origin files:scan frtest >/dev/null
+RUN_OUT=$(run_on ngb-frt-origin backup:run offsite -l disaster-test)
+SNAP=$(printf '%s\n' "$RUN_OUT" | head -1 | awk -F'snapshot ' '{print $2}' | tr -d ',')
+[ -n "$SNAP" ] || fail "no snapshot id from backup:run"
+ok "test data backed up, snapshot $SNAP"
+
+docker cp ngb-frt-origin:/tmp/kit.json /tmp/ngb-frt-kit.json
+docker exec ngb-frt-origin sh -c "cat /tmp/pass" > /tmp/ngb-frt-pass
+docker run -d --name ngb-frt-restore --network "$NET" -e SQLITE_DATABASE=nextcloud \
+	-e NEXTCLOUD_ADMIN_USER=admin -e NEXTCLOUD_ADMIN_PASSWORD=admin \
+	-v "$APP:/var/www/html/custom_apps/ng_backup:ro" -v "$SHARED:/mnt/shared" "$IMAGE" >/dev/null
+for i in $(seq 1 90); do run_on ngb-frt-restore status 2>/dev/null | grep -q "installed: true" && break; sleep 3; done
+docker exec ngb-frt-restore chown www-data:www-data /var/www/html/custom_apps
+run_on ngb-frt-restore app:enable ng_backup >/dev/null
+docker cp /tmp/ngb-frt-kit.json ngb-frt-restore:/tmp/kit.json
+docker exec ngb-frt-restore chmod 644 /tmp/kit.json
+docker cp /tmp/ngb-frt-pass ngb-frt-restore:/tmp/pass
+ok "fresh restore instance up"
+
+run_on ngb-frt-restore backup:key:import /tmp/kit.json --passphrase-file=/tmp/pass >/dev/null || fail "key import"
+run_on ngb-frt-restore backup:target:add offsite local -a null::null -o datadir=/mnt/shared --path=repo >/dev/null || fail "target add on the restore instance"
+run_on ngb-frt-restore backup:list offsite | grep -q "$SNAP" || fail "the origin's snapshot is not listed after connecting the location"
+ok "recovery kit imported, existing repository adopted, snapshot visible"
+
+run_on ngb-frt-restore backup:restore:full offsite "$SNAP" >/dev/null || fail "restore:full"
+ok "backup:restore:full completed"
+
+# Everything below must work in a FRESH occ process (a new PHP process per docker exec), since
+# earlier bugs here only showed up after config.php's secret was rewritten mid-restore.
+run_on ngb-frt-restore backup:status >/dev/null || fail "backup:status fails after restore (own key/target undecryptable?)"
+run_on ngb-frt-restore user:list | grep -q frtest || fail "the backed-up user is missing from the restored database"
+docker exec ngb-frt-restore test -f /var/www/html/data/frtest/files/Docs/note.txt || fail "restored file is missing"
+[ "$(docker exec ngb-frt-restore cat /var/www/html/data/frtest/files/Docs/note.txt)" = "hello disaster recovery" ] || fail "restored file content differs"
+run_on ngb-frt-restore files:scan frtest >/dev/null || fail "files:scan fails after restore"
+ok "database, files and ng_backup's own state are all intact and usable after the restore"
+
+run_on ngb-frt-restore backup:run offsite -l post-restore-check >/dev/null || fail "a new backup after the restore fails"
+ok "the restored instance can run a new backup of its own"
+
+echo "FULL RESTORE ROUNDTRIP PASS"