Phase 2: per-user backup and restore via user_migration

Wires the existing RepositoryExportDestination/RepositoryImportSource (see
lib/UserMigration/) into user_migration's own UserMigrationService, resolved on demand
through a new UserMigrationServiceLocator since the app is an optional dependency
(PLAN.md 3.8) -- without it, only this feature is unavailable, the full backup still
works.

New: UserBackupService::backupUser() (occ backup:backup:user) streams a user_migration
export straight into the repository, under the same shared location lock as a regular
backup. UserRestoreService::restoreUser() (occ backup:restore:user) never imports over a
live account: --mode=replace safety-exports the current state first, then deletes and
recreates the account from the backup under the same uid; --mode=as-backup restores into
a new "<uid>-bak" account instead, since Nextcloud cannot rename a uid.

The catalog now also tracks user export manifests (Repository::recordUserExport/
listUserExports/forgetUserExport/isRecordedUserExport), rollback-protected like a
snapshot: listUserExports() verifies each one is still present on the location, and
restore only ever reads a manifest the verified catalog actually recorded, never an
arbitrary caller-supplied path. prune()'s existing raw users/ scan for blob retention is
unchanged. A new short exclusive "catalog" lock (PruneService::catalogLockKey())
serializes the catalog write itself, so two concurrent per-user backups (or one
alongside a full backup) can no longer race to write the same next generation and
silently drop one of them -- the broader per-target shared lock only ever protected
against a concurrent cleanup, not against other shared holders.

Two real bugs found by testing this against a live Nextcloud instance, not by unit
tests (RepositoryExportDestination/RepositoryImportSource implement OCP interfaces that
plain PHPUnit can't load, see tests/Unit/Repository/UserExportTest.php's docblock; the
new tests/integration/user-roundtrip.sh covers the real round trip instead):
- RepositoryImportSource::copyToFolder() double-closed the stream it handed to
  putContent()/newFile() (both already close it themselves), which throws a TypeError on
  PHP 8 and broke every restored file with content.
- A replace-mode restore failed on NotPermittedException: IRootFolder::getUserFolder()
  caches a Folder per uid for the process lifetime, so after delete+recreate of the same
  uid the import still got the deleted account's (now storage-less) folder. Fixed by
  dispatching FilesystemTornDownEvent, which Root already listens for to clear exactly
  that cache -- no internal OC\ classes needed.

Local review (CodeRabbit + Codex) against this diff found three more real issues, all
fixed: the catalog write race above, a failed as-backup import leaving a broken stub
account behind (now deleted on failure), and an export stream leak on a read/backend
failure in RepositoryExportDestination::copyFolder() (now closed in a finally).

Deliberately left out: wiring per-user export into the automatic backup schedule
(on-demand via occ only, for now) and retention/pruning of old user exports -- both open
design questions, not yet decided. The lease covering a single export/import still has a
fixed TTL (3600s) with no mid-call refresh, since UserMigrationService exposes no
progress; a resumable, step-based per-user backup (like the main BackupService run)
would remove that cap but is a bigger change than this pass.

lib/Repository/Catalog.php

@@ -28,6 +28,8 @@ final class Catalog {
 	public array $snapshots = [];
 	/** @var array<string, true> */
 	public array $trash = [];
+	/** @var array<string, true> manifest path => true, for a per-user export (users/<uid>/<exportId>) */
+	public array $userExports = [];
 	public string $hash = '';
 
 	public function __construct(
@@ -39,7 +41,7 @@ final class Catalog {
 	}
 
 	/** Load and verify the newest catalog; create the first one for repositories that have none. */
-	public function load(callable $listSnapshots, callable $listTrash): void {
+	public function load(callable $listSnapshots, callable $listTrash, callable $listUserExports): void {
 		$gens = $this->generations();
 		if ($gens === []) {
 			// First use (new or pre-catalog repository): adopt the current state as generation 1.
@@ -49,6 +51,7 @@ final class Catalog {
 			}
 			$this->snapshots = array_fill_keys($listSnapshots(), true);
 			$this->trash = array_fill_keys($listTrash(), true);
+			$this->userExports = array_fill_keys($listUserExports(), true);
 			$this->write();
 			return;
 		}
@@ -76,6 +79,9 @@ final class Catalog {
 		$this->hash = $hash;
 		$this->snapshots = array_fill_keys($data['snapshots'], true);
 		$this->trash = array_fill_keys($data['trash'], true);
+		// Catalogs written before user exports existed have no such key: default to empty rather
+		// than adopting the location's current users/ listing (that would skip verification).
+		$this->userExports = array_fill_keys($data['userExports'] ?? [], true);
 		$this->anchor?->set($this->repositoryId, $this->gen, $this->hash);
 	}
 
@@ -83,7 +89,8 @@ final class Catalog {
 	public function write(): void {
 		$next = $this->gen + 1;
 		$plain = json_encode(['repository' => $this->repositoryId, 'gen' => $next, 'time' => gmdate('c'), 'prev' => $this->hash,
-			'snapshots' => array_keys($this->snapshots), 'trash' => array_keys($this->trash)], JSON_THROW_ON_ERROR);
+			'snapshots' => array_keys($this->snapshots), 'trash' => array_keys($this->trash),
+			'userExports' => array_keys($this->userExports)], JSON_THROW_ON_ERROR);
 		$encrypted = $this->cipher->encryptString($plain, $this->ad($next));
 		$stream = fopen('php://memory', 'w+b');
 		fwrite($stream, $encrypted);

lib/Repository/Repository.php

@@ -91,7 +91,8 @@ final class Repository {
 		$this->catalog = new Catalog($this->backend, $this->cipher, $this->repositoryId, $anchor);
 		$this->catalog->load(
 			fn () => array_map('basename', $this->backend->list('snapshots')),
-			fn () => array_map('basename', $this->backend->list('trash/info')));
+			fn () => array_map('basename', $this->backend->list('trash/info')),
+			fn () => $this->backend->list('users'));
 	}
 
 	/** Refuse uploads that would make the stored data larger than this (null = no limit). */
@@ -374,6 +375,50 @@ final class Repository {
 		$this->backend->delete('trash/info/' . $snapshotId);
 	}
 
+	/** Record a user_migration export's manifest in the catalog (rollback-protected like a snapshot). */
+	public function recordUserExport(string $manifestPath): void {
+		$this->catalog->userExports[$manifestPath] = true;
+		$this->catalog->write();
+	}
+
+	/**
+	 * User export manifests according to the verified catalog, newest first. A manifest the
+	 * catalog lists but the location no longer has means it was deleted or hidden behind NG
+	 * Backup's back, same as a missing snapshot (see listSnapshots()).
+	 *
+	 * @return list<string>
+	 */
+	public function listUserExports(?string $uid = null): array {
+		$prefix = $uid !== null ? 'users/' . $uid . '/' : 'users/';
+		$out = [];
+		foreach (array_keys($this->catalog->userExports) as $path) {
+			if (!str_starts_with($path, $prefix)) {
+				continue;
+			}
+			if (!$this->backend->exists($path)) {
+				throw new RepositoryException("User export $path is missing on the location (deleted or hidden outside NG Backup)");
+			}
+			$out[] = $path;
+		}
+		sort($out, SORT_STRING);
+		return array_reverse($out);
+	}
+
+	/** Whether $manifestPath is a user export the verified catalog actually recorded. */
+	public function isRecordedUserExport(string $manifestPath): bool {
+		return isset($this->catalog->userExports[$manifestPath]);
+	}
+
+	/** Permanently delete a user export. Its blobs are freed by the next prune() like any other. */
+	public function forgetUserExport(string $manifestPath): void {
+		if (!isset($this->catalog->userExports[$manifestPath])) {
+			throw new RepositoryException("$manifestPath is not a recorded user export");
+		}
+		$this->backend->delete($manifestPath);
+		unset($this->catalog->userExports[$manifestPath]);
+		$this->catalog->write();
+	}
+
 	/** @return array<string, array{forgottenAt:int, by:string, db:?string, dbInTrash:?string, time:?string, label:string}> */
 	public function trash(): array {
 		$out = [];