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/Service/UserRestoreService.php

@@ -0,0 +1,137 @@
+<?php
+
+declare(strict_types=1);
+
+// SPDX-FileCopyrightText: 2026 Dillard Blom
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+namespace OCA\NgBackup\Service;
+
+use OCA\NgBackup\Db\Target;
+use OCA\NgBackup\UserMigration\RepositoryExportDestination;
+use OCA\NgBackup\UserMigration\RepositoryImportSource;
+use OCA\NgBackup\UserMigration\UserMigrationServiceLocator;
+use OCP\EventDispatcher\IEventDispatcher;
+use OCP\Files\Events\Node\FilesystemTornDownEvent;
+use OCP\IUser;
+use OCP\IUserManager;
+use OCP\Lock\LockedException;
+use OCP\Security\ISecureRandom;
+use OCP\UserMigration\UserMigrationException;
+
+/**
+ * Restoring a user from a user_migration export (see UserBackupService), never over an existing
+ * account:
+ *  - replace: a safety export of the current state goes into the repository first, then the
+ *    account is deleted and recreated fresh from the backup, under the same uid;
+ *  - as-backup: the backup is restored into a new account "<uid>-bak" (or "-bak-2", ...) instead,
+ *    so an admin can compare and transfer by hand. Nextcloud cannot rename a uid, so the *backup*
+ *    gets the new name, never the existing account.
+ */
+final class UserRestoreService {
+	public const MODE_REPLACE = 'replace';
+	public const MODE_AS_BACKUP = 'as-backup';
+
+	public function __construct(
+		private TargetService $targets,
+		private LeaseService $leases,
+		private UserMigrationServiceLocator $locator,
+		private IUserManager $userManager,
+		private ISecureRandom $random,
+		private IEventDispatcher $events,
+	) {
+	}
+
+	/** @throws UserMigrationException when user_migration is not enabled, or the restore itself fails */
+	public function restoreUser(Target $target, string $manifestPath, string $mode = self::MODE_REPLACE): IUser {
+		$service = $this->locator->get();
+		return $this->withSharedLock($target, function () use ($target, $manifestPath, $mode, $service): IUser {
+			$repo = $this->targets->repository($target);
+			// Only ever read a manifest the verified catalog actually recorded: a path alone
+			// (even one this app generated before) proves nothing about it still being current
+			// or genuine once the catalog's rollback protection is supposed to vouch for it.
+			if (!$repo->isRecordedUserExport($manifestPath)) {
+				throw new \InvalidArgumentException("$manifestPath is not a recorded user export for this location");
+			}
+			$source = new RepositoryImportSource($repo, $manifestPath);
+			$originalUid = $source->getOriginalUid();
+
+			if ($mode === self::MODE_AS_BACKUP) {
+				$backupUid = $this->freeBackupUid($originalUid);
+				$user = $this->userManager->createUser($backupUid, $this->random->generate(32));
+				if ($user === false) {
+					throw new \RuntimeException("Could not create the account $backupUid");
+				}
+				try {
+					return $service->import($source, $user);
+				} catch (\Throwable $e) {
+					// A partially-imported, never-used account left behind is strictly worse
+					// than no account at all; the original source account was never touched.
+					$user->delete();
+					throw $e;
+				}
+			}
+
+			if ($mode !== self::MODE_REPLACE) {
+				throw new \InvalidArgumentException("Unknown restore mode: $mode");
+			}
+			$existing = $this->userManager->get($originalUid);
+			$safetyManifestPath = null;
+			if ($existing !== null) {
+				// Never import over a live account: export its current state first, so nothing
+				// is lost if the restore turns out to be the wrong choice.
+				$safety = new RepositoryExportDestination($repo, $originalUid);
+				$service->export($safety, $existing);
+				$safetyManifestPath = $safety->manifestPath();
+				// Same race as UserBackupService::backupUser(): serialize the catalog write
+				// itself against any other concurrent backup/restore for this target.
+				$this->withCatalogLock($target, fn () => $repo->recordUserExport($safetyManifestPath));
+				if (!$existing->delete()) {
+					throw new \RuntimeException("Could not delete the existing account $originalUid before restoring; its safety export is at $safetyManifestPath");
+				}
+				// IRootFolder caches a Folder per uid for the lifetime of this process; without
+				// this it would still hand the just-deleted account's (now storage-less) folder
+				// to the import below, and every write would fail.
+				$this->events->dispatchTyped(new FilesystemTornDownEvent());
+			}
+			try {
+				return $service->import($source, null);
+			} catch (\Throwable $e) {
+				// The original account is already gone at this point (or never existed); a
+				// failure here can only be reported, not undone in place. Its safety export
+				// (if any) is the recovery path, already recorded above.
+				throw new UserMigrationException(
+					"Could not restore $originalUid" . ($safetyManifestPath !== null ? "; its safety export is at $safetyManifestPath" : '') . ': ' . $e->getMessage(),
+					0,
+					$e,
+				);
+			}
+		});
+	}
+
+	private function freeBackupUid(string $uid): string {
+		$candidate = $uid . '-bak';
+		for ($n = 2; $this->userManager->userExists($candidate); $n++) {
+			$candidate = $uid . '-bak-' . $n;
+		}
+		return $candidate;
+	}
+
+	private function withSharedLock(Target $target, callable $fn): mixed {
+		try {
+			// See UserBackupService::withSharedLock(): UserMigrationService exposes no progress,
+			// so this lease cannot be refreshed mid-call.
+			return $this->leases->with(PruneService::lockKey($target), LeaseService::SHARED, 3600, $fn);
+		} catch (LockedException) {
+			throw new \RuntimeException('A cleanup of ' . $target->getName() . ' is in progress; try again later');
+		}
+	}
+
+	private function withCatalogLock(Target $target, callable $fn): mixed {
+		try {
+			return $this->leases->with(PruneService::catalogLockKey($target), LeaseService::EXCLUSIVE, 30, $fn);
+		} catch (LockedException) {
+			throw new \RuntimeException('Another catalog write for ' . $target->getName() . ' is in progress; try again');
+		}
+	}
+}