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/UserMigration/RepositoryExportDestination.php

@@ -65,8 +65,11 @@ final class RepositoryExportDestination implements IExportDestination {
 				if ($stream === false) {
 					throw new \RuntimeException('Cannot read ' . $node->getPath());
 				}
-				$this->addFileAsStream($target, $stream);
-				fclose($stream);
+				try {
+					$this->addFileAsStream($target, $stream);
+				} finally {
+					fclose($stream);
+				}
 			}
 		}
 	}

lib/UserMigration/RepositoryImportSource.php

@@ -109,7 +109,14 @@ final class RepositoryImportSource implements IImportSource {
 						$destination->newFile($name, $stream);
 					}
 				} finally {
-					fclose($stream);
+					// putContent()/newFile() already close the stream once they've consumed it:
+					// despite the @return resource docblock above, $stream is no longer a
+					// resource by the time we get here (verified against a real storage; a
+					// double fclose() throws a TypeError on PHP 8).
+					/** @psalm-suppress RedundantConditionGivenDocblockType */
+					if (is_resource($stream)) {
+						fclose($stream);
+					}
 				}
 			}
 		}

lib/UserMigration/UserMigrationServiceLocator.php

@@ -0,0 +1,35 @@
+<?php
+
+declare(strict_types=1);
+
+// SPDX-FileCopyrightText: 2026 Dillard Blom
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+namespace OCA\NgBackup\UserMigration;
+
+use OCP\App\IAppManager;
+use OCP\Server;
+use OCP\UserMigration\UserMigrationException;
+
+/**
+ * Resolves user_migration's own (internal, non-public) UserMigrationService on demand.
+ *
+ * Unlike files_external, user_migration is an optional dependency: without it, only per-user
+ * backup/restore is unavailable, the full backup still works. The class is never autoloaded by
+ * composer; everything that touches it is behind this one class.
+ */
+final class UserMigrationServiceLocator {
+	public function __construct(
+		private IAppManager $appManager,
+	) {
+	}
+
+	/** @throws UserMigrationException when user_migration is not enabled anywhere */
+	public function get(): object {
+		if (!$this->appManager->isEnabledForAnyone('user_migration')) {
+			throw new UserMigrationException('The user_migration app is not enabled; per-user backup/restore is unavailable');
+		}
+		$this->appManager->loadApp('user_migration');
+		return Server::get(\OCA\UserMigration\Service\UserMigrationService::class);
+	}
+}