Prepare the 0.1.0-alpha.1 release

info.xml's version field is restricted by Nextcloud's own info.xsd to plain
numeric SemVer, no pre-release suffix, so the alpha/beta/rc stage from
PLAN.md's release table lives in the git tag and CHANGELOG instead; noted
that in PLAN.md so it isn't rediscovered later. Bumped the version, wrote
an honest description for an alpha (feature-complete for phase 1, not for
production), and added CHANGELOG.md.

README: new "Storage backend experiences" section, seeded with the Hetzner
Storage Box sub-account root-path quirk found while testing a real SFTP
target (root must be "home", not "/"), open for others to extend via PR.

.github/workflows/ci.yml

@@ -25,6 +25,18 @@ jobs:
       - run: composer install --no-interaction --no-progress
       - run: vendor/bin/phpunit -c tests/phpunit.xml
 
+  psalm:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.2'
+          extensions: sodium, zip
+          coverage: none
+      - run: composer install --no-interaction --no-progress
+      - run: composer psalm
+
   integration:
     # Full round trip (key, kit, location, backup, incremental, restore modes, database dump and
     # restore, retention, trash) on a fresh Nextcloud per version and database.
@@ -38,3 +50,13 @@ jobs:
       - uses: actions/checkout@v4
       - name: Round trip on Nextcloud ${{ matrix.nextcloud }} / ${{ matrix.database }}
         run: tests/integration/matrix.sh "${{ matrix.nextcloud }}" "${{ matrix.database }}"
+
+  integration-targets:
+    # Same round trip, but through the real S3 (s3mock) and SFTP backends instead of a local
+    # path, so files_external's AmazonS3/SFTP backend and auth classes are actually exercised.
+    # Backend correctness does not depend on the Nextcloud version or database, so this runs once.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Round trip against S3 and SFTP
+        run: tests/integration/targets-matrix.sh

CHANGELOG.md

@@ -0,0 +1,44 @@
+# Changelog
+
+All notable changes to NG Backup are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versioning follows the stages in
+`PLAN.md` section 9. The `<version>` in `appinfo/info.xml` is plain SemVer-numeric (Nextcloud's
+own `info.xsd` doesn't allow a `-alpha`/`-beta`/`-rc` suffix there); the stability stage is instead
+carried by the git tag, the release, and this file.
+
+## [0.1.0-alpha.1] - 2026-10-05
+
+First public alpha. Feature-complete for phase 1: scheduled, encrypted, incremental backups, and
+restore of files and folders. **Not for production use** — test on a copy of production (dev,
+test, staging). Full disaster recovery (`backup:restore:full` on a fresh installation) is phase 2
+and not implemented yet.
+
+### Added
+- Encrypted (XChaCha20-Poly1305), content-addressed, deduplicated, incremental backups, streamed
+  from source to destination without a local copy of the data.
+- Backup locations via files_external's own backend/auth classes, without ever mounting the
+  location: S3 (and compatible services), SFTP, WebDAV, FTP, Swift, or a local path.
+- A recovery kit with up to three passphrase slots, mandatory download-and-confirm before the
+  first backup runs, and an optional encrypted copy by email.
+- Resumable, time-boxed background jobs (database dump, file walk, upload), so a run survives
+  short PHP time limits and a crash is resumed, never restarted, without leaving the instance in
+  maintenance mode.
+- Database dump and restore without external tools, via Nextcloud's own `IDBConnection`/DBAL,
+  streamed through the same pipeline as file data.
+- Restore of files and folders via the web interface and `occ`, into a new folder, merged, or
+  replacing the original (with the previous content going to the trash).
+- Retention policy (last/daily/weekly/monthly), prune with pack repacking, and a snapshot trash
+  with a configurable deletion delay.
+- Append-only locations and documented recommendations against ransomware and a compromised
+  server (object lock, delete-less credentials, off-site copies).
+- Admin settings page (locations, schedule, retention, key management) and a JSON API.
+- Notifications and an admin setup check for a failed or overdue backup.
+- CI: unit tests on PHP 8.2–8.4, and an end-to-end backup→restore round trip on Nextcloud 32–35 ×
+  SQLite/MariaDB/PostgreSQL, and against real S3 and SFTP backends (not just a local path).
+
+### Known limitations
+- No full/disaster-recovery restore yet (phase 2).
+- No per-user backup/restore via user_migration yet (phase 2).
+- No FTP/SMB coverage in CI yet, and no verification/checksum-audit command yet (phase 2).
+- See the "Storage backend experiences" section of the README for provider-specific quirks found
+  so far (e.g. Hetzner Storage Box sub-accounts).

PLAN.md

@@ -338,6 +338,11 @@ een backup-app die niet betrouwbaar is, is erger dan geen backup-app.
 Volgorde: fase 1 grondig testen, reviewen en debuggen; dan nadenken over 0.1.0-alpha.1. Een
 minimale volledige restore (`occ backup:restore:full` op een verse installatie) komt vóór de beta.
 
+**Let op (ontdekt 2026-10-05):** Nextcloud's eigen `info.xsd` staat voor `<version>` alleen
+`[0-9]+(\.[0-9]+){0,2}` toe — geen `-alpha`/`-beta`/`-rc`-achtervoegsel. De stabiliteitsaanduiding
+uit deze tabel gaat dus niet in `info.xml` (dat blijft gewoon oplopend, bijv. `0.1.0`), maar in de
+git-tag (`v0.1.0-alpha.1`), de GitHub/Gitea release (gemarkeerd als pre-release) en de CHANGELOG.
+
 ## Bijlage: lessen uit nextcloud/backup (test NC34, 2026-10-01)
 
 - Externe programma's (`pg_dump`) en extensies (`pgsql`, `mysqli`) → onbruikbaar op standaard/hosted.

README.md

@@ -106,6 +106,19 @@ What you should do on the location (strongly recommended):
 - **Raw restore** of any path (for example `config/`) to a local directory: `occ backup:restore ... --to-directory=DIR`.
 - **Whole server** (disaster recovery onto a fresh installation): planned for phase 2.
 
+## Storage backend experiences
+
+Notes from actually running a backend, beyond what's in files_external's own documentation.
+Contributions welcome via PR — add what you ran into with your own provider.
+
+- **Hetzner Storage Box, sub-account:** the SFTP backend's `root` option must be `home`, not `/`.
+  A sub-account's SFTP login lands in `/home` (confirmed via `pwd()` after login); writing to the
+  literal chroot root (`/`) fails with a generic `NET_SFTP_STATUS_FAILURE` from the SFTP server,
+  while the same write under `home` (or a path below it) succeeds. This affects any backend option
+  form that lets you set a path relative to the account's root, not just ng_backup. Not yet
+  verified whether this also applies to a Hetzner Storage Box **main** account (only tested with a
+  sub-account so far) — if you've tried a main account, please say so in a PR.
+
 ## Commands
 
 | Command | Purpose |

appinfo/info.xml

@@ -4,8 +4,12 @@
     <id>ng_backup</id>
     <name>NG Backup</name>
     <summary>Encrypted, incremental backups of your Nextcloud with restore from the web interface</summary>
-    <description><![CDATA[Work in progress, not ready for use.]]></description>
-    <version>0.0.19</version>
+    <description><![CDATA[Alpha: feature-complete for scheduled, encrypted, incremental backups to
+S3/SFTP/WebDAV/local, with restore of files and folders from the web interface and occ. Meant for
+testing on a copy of production (dev, test, staging) -- not yet for production use, and full
+disaster recovery is not implemented yet. See the recovery kit section of the README before
+relying on this for anything.]]></description>
+    <version>0.1.0</version>
     <licence>agpl</licence>
     <author>Dillard Blom</author>
     <namespace>NgBackup</namespace>

lib/AppInfo/Application.php

@@ -12,7 +12,7 @@ use OCP\AppFramework\Bootstrap\IBootContext;
 use OCP\AppFramework\Bootstrap\IBootstrap;
 use OCP\AppFramework\Bootstrap\IRegistrationContext;
 
-class Application extends App implements IBootstrap {
+final class Application extends App implements IBootstrap {
 	public const APP_ID = 'ng_backup';
 
 	public function __construct() {

lib/Backend/BackendException.php

@@ -7,5 +7,5 @@ declare(strict_types=1);
 
 namespace OCA\NgBackup\Backend;
 
-class BackendException extends \RuntimeException {
+final class BackendException extends \RuntimeException {
 }

lib/Backend/IBackend.php

@@ -27,6 +27,13 @@ interface IBackend {
 
 	public function exists(string $path): bool;
 
+	/**
+	 * Move an object within the same location (used for the trash). Backends must use a native
+	 * rename, not a read+write copy: some storages (e.g. SFTP) cannot reliably read and write on
+	 * the same connection at once, since the read side is a lazily-pulled stream.
+	 */
+	public function move(string $from, string $to): void;
+
 	/** @return list<string> object paths below $prefix (recursive) */
 	public function list(string $prefix): array;
 

lib/Backend/LocalBackend.php

@@ -106,6 +106,17 @@ final class LocalBackend implements IBackend {
 		@unlink($this->abs($path));
 	}
 
+	public function move(string $from, string $to): void {
+		$target = $this->abs($to);
+		$dir = dirname($target);
+		if (!is_dir($dir) && !mkdir($dir, 0700, true) && !is_dir($dir)) {
+			throw new BackendException('Cannot create ' . $dir);
+		}
+		if (!rename($this->abs($from), $target)) {
+			throw new BackendException("Cannot move $from to $to");
+		}
+	}
+
 	private function abs(string $path): string {
 		if (str_contains($path, '..') || str_starts_with($path, '/')) {
 			throw new BackendException('Invalid path: ' . $path);

lib/Backend/StorageBackend.php

@@ -115,6 +115,14 @@ final class StorageBackend implements IBackend {
 		$this->storage->unlink($this->abs($path));
 	}
 
+	public function move(string $from, string $to): void {
+		$target = $this->abs($to);
+		$this->mkdirs(dirname($target));
+		if (!$this->storage->rename($this->abs($from), $target)) {
+			throw new BackendException("Cannot move $from to $to");
+		}
+	}
+
 	private function listInto(string $dir, array &$result): void {
 		if (!$this->storage->is_dir($dir)) {
 			return;

lib/BackgroundJob/BackupJob.php

@@ -22,7 +22,7 @@ use Psr\Log\LoggerInterface;
  * With system cron a step may take minutes; with webcron/AJAX cron it is kept short so it fits
  * in a normal web request (hosted Nextcloud).
  */
-class BackupJob extends TimedJob {
+final class BackupJob extends TimedJob {
 	public function __construct(
 		ITimeFactory $time,
 		private BackupService $backups,

lib/BackgroundJob/RestoreJob.php

@@ -16,7 +16,7 @@ use OCP\BackgroundJob\QueuedJob;
 use Psr\Log\LoggerInterface;
 
 /** Runs a restore requested from the web interface, outside the web request. */
-class RestoreJob extends QueuedJob {
+final class RestoreJob extends QueuedJob {
 	public function __construct(
 		ITimeFactory $time,
 		private RunMapper $runs,

lib/Command/Browse.php

@@ -15,7 +15,7 @@ use Symfony\Component\Console\Input\InputArgument;
 use Symfony\Component\Console\Input\InputInterface;
 use Symfony\Component\Console\Output\OutputInterface;
 
-class Browse extends Command {
+final class Browse extends Command {
 	public function __construct(
 		private TargetService $targets,
 		private RestoreService $restore,

lib/Command/KeyConfirm.php

@@ -14,7 +14,7 @@ use Symfony\Component\Console\Input\InputOption;
 use Symfony\Component\Console\Output\OutputInterface;
 use Symfony\Component\Console\Question\Question;
 
-class KeyConfirm extends Command {
+final class KeyConfirm extends Command {
 	public const STATEMENT = 'I have downloaded the recovery kit and stored it safely, outside this server. '
 		. 'I understand that keeping these keys safe is my own responsibility and that backups cannot be restored without them.';
 	public const CONFIRMATION = 'Yes, I confirm';

lib/Command/KeyInit.php

@@ -14,7 +14,7 @@ use Symfony\Component\Console\Input\InputOption;
 use Symfony\Component\Console\Output\OutputInterface;
 use Symfony\Component\Console\Question\Question;
 
-class KeyInit extends Command {
+final class KeyInit extends Command {
 	public function __construct(
 		private KeyService $keys,
 	) {

lib/Command/KeyKit.php

@@ -13,7 +13,7 @@ use Symfony\Component\Console\Input\InputInterface;
 use Symfony\Component\Console\Input\InputOption;
 use Symfony\Component\Console\Output\OutputInterface;
 
-class KeyKit extends Command {
+final class KeyKit extends Command {
 	public function __construct(
 		private KeyService $keys,
 		private \OCA\NgBackup\Service\AlertService $alerts,

lib/Command/KeySlotAdd.php

@@ -10,7 +10,7 @@ namespace OCA\NgBackup\Command;
 use OCA\NgBackup\Service\KeyService;
 use OCA\NgBackup\Service\KeySlotService;
 
-class KeySlotAdd extends KeySlots {
+final class KeySlotAdd extends KeySlots {
 	public function __construct(KeyService $keys, KeySlotService $slots) {
 		parent::__construct($keys, $slots, 'add');
 	}

lib/Command/KeySlotRemove.php

@@ -10,7 +10,7 @@ namespace OCA\NgBackup\Command;
 use OCA\NgBackup\Service\KeyService;
 use OCA\NgBackup\Service\KeySlotService;
 
-class KeySlotRemove extends KeySlots {
+final class KeySlotRemove extends KeySlots {
 	public function __construct(KeyService $keys, KeySlotService $slots) {
 		parent::__construct($keys, $slots, 'remove');
 	}

lib/Command/KeySlotReplace.php

@@ -10,7 +10,7 @@ namespace OCA\NgBackup\Command;
 use OCA\NgBackup\Service\KeyService;
 use OCA\NgBackup\Service\KeySlotService;
 
-class KeySlotReplace extends KeySlots {
+final class KeySlotReplace extends KeySlots {
 	public function __construct(KeyService $keys, KeySlotService $slots) {
 		parent::__construct($keys, $slots, 'replace');
 	}

lib/Command/ListSnapshots.php

@@ -15,7 +15,7 @@ use Symfony\Component\Console\Input\InputArgument;
 use Symfony\Component\Console\Input\InputInterface;
 use Symfony\Component\Console\Output\OutputInterface;
 
-class ListSnapshots extends Command {
+final class ListSnapshots extends Command {
 	public function __construct(
 		private TargetService $targets,
 		private SnapshotMapper $snapshots,

lib/Command/Prune.php

@@ -15,7 +15,7 @@ use Symfony\Component\Console\Input\InputInterface;
 use Symfony\Component\Console\Input\InputOption;
 use Symfony\Component\Console\Output\OutputInterface;
 
-class Prune extends Command {
+final class Prune extends Command {
 	public function __construct(
 		private TargetService $targets,
 		private PruneService $prune,

lib/Command/Restore.php

@@ -15,7 +15,7 @@ use Symfony\Component\Console\Input\InputInterface;
 use Symfony\Component\Console\Input\InputOption;
 use Symfony\Component\Console\Output\OutputInterface;
 
-class Restore extends Command {
+final class Restore extends Command {
 	public function __construct(
 		private TargetService $targets,
 		private RestoreService $restore,

lib/Command/Retention.php

@@ -14,7 +14,7 @@ use Symfony\Component\Console\Input\InputInterface;
 use Symfony\Component\Console\Input\InputOption;
 use Symfony\Component\Console\Output\OutputInterface;
 
-class Retention extends Command {
+final class Retention extends Command {
 	public function __construct(
 		private PruneService $prune,
 	) {

lib/Command/RunBackup.php

@@ -16,7 +16,7 @@ use Symfony\Component\Console\Input\InputInterface;
 use Symfony\Component\Console\Input\InputOption;
 use Symfony\Component\Console\Output\OutputInterface;
 
-class RunBackup extends Command {
+final class RunBackup extends Command {
 	public function __construct(
 		private BackupService $backups,
 		private TargetService $targets,

lib/Command/Status.php

@@ -15,7 +15,7 @@ use Symfony\Component\Console\Helper\Table;
 use Symfony\Component\Console\Input\InputInterface;
 use Symfony\Component\Console\Output\OutputInterface;
 
-class Status extends Command {
+final class Status extends Command {
 	public function __construct(
 		private KeyService $keys,
 		private TargetService $targets,

lib/Command/TargetAdd.php

@@ -15,7 +15,7 @@ use Symfony\Component\Console\Input\InputInterface;
 use Symfony\Component\Console\Input\InputOption;
 use Symfony\Component\Console\Output\OutputInterface;
 
-class TargetAdd extends Command {
+final class TargetAdd extends Command {
 	public function __construct(
 		private TargetService $targets,
 		private KeyService $keys,

lib/Command/TargetAppendOnly.php

@@ -13,7 +13,7 @@ use Symfony\Component\Console\Input\InputArgument;
 use Symfony\Component\Console\Input\InputInterface;
 use Symfony\Component\Console\Output\OutputInterface;
 
-class TargetAppendOnly extends Command {
+final class TargetAppendOnly extends Command {
 	public function __construct(
 		private TargetService $targets,
 		private \OCA\NgBackup\Service\AlertService $alerts,

lib/Command/TargetBackends.php

@@ -12,7 +12,7 @@ use OCA\NgBackup\Service\TargetService;
 use Symfony\Component\Console\Input\InputInterface;
 use Symfony\Component\Console\Output\OutputInterface;
 
-class TargetBackends extends Base {
+final class TargetBackends extends Base {
 	public function __construct(
 		private TargetService $targets,
 	) {

lib/Command/TargetLimit.php

@@ -13,7 +13,7 @@ use Symfony\Component\Console\Input\InputArgument;
 use Symfony\Component\Console\Input\InputInterface;
 use Symfony\Component\Console\Output\OutputInterface;
 
-class TargetLimit extends Command {
+final class TargetLimit extends Command {
 	public function __construct(
 		private TargetService $targets,
 	) {

lib/Command/TargetList.php

@@ -13,7 +13,7 @@ use Symfony\Component\Console\Input\InputInterface;
 use Symfony\Component\Console\Input\InputOption;
 use Symfony\Component\Console\Output\OutputInterface;
 
-class TargetList extends Base {
+final class TargetList extends Base {
 	public function __construct(
 		private TargetService $targets,
 	) {

lib/Command/TargetRemove.php

@@ -13,7 +13,7 @@ use Symfony\Component\Console\Input\InputArgument;
 use Symfony\Component\Console\Input\InputInterface;
 use Symfony\Component\Console\Output\OutputInterface;
 
-class TargetRemove extends Command {
+final class TargetRemove extends Command {
 	public function __construct(
 		private TargetService $targets,
 		private \OCA\NgBackup\Service\AlertService $alerts,

lib/Command/TargetTrustCurrent.php

@@ -22,7 +22,7 @@ use Symfony\Component\Console\Question\Question;
  * legitimate cases (e.g. the location was restored from the provider's own snapshot), only from
  * occ, audited and announced to all administrators.
  */
-class TargetTrustCurrent extends Command {
+final class TargetTrustCurrent extends Command {
 	public function __construct(
 		private TargetService $targets,
 		private IAppConfig $appConfig,

lib/Command/Trash.php

@@ -15,7 +15,7 @@ use Symfony\Component\Console\Input\InputArgument;
 use Symfony\Component\Console\Input\InputInterface;
 use Symfony\Component\Console\Output\OutputInterface;
 
-class Trash extends Command {
+final class Trash extends Command {
 	public function __construct(
 		private TargetService $targets,
 		private KeyService $keys,

lib/Command/TrashRestore.php

@@ -14,7 +14,7 @@ use Symfony\Component\Console\Input\InputArgument;
 use Symfony\Component\Console\Input\InputInterface;
 use Symfony\Component\Console\Output\OutputInterface;
 
-class TrashRestore extends Command {
+final class TrashRestore extends Command {
 	public function __construct(
 		private TargetService $targets,
 		private PruneService $prune,

lib/Controller/AdminApiController.php

@@ -32,7 +32,7 @@ use OCP\IUserSession;
  * JSON API for the admin settings page. Every method requires an admin (the AppFramework
  * default for controllers without NoAdminRequired) and a valid CSRF token.
  */
-class AdminApiController extends Controller {
+final class AdminApiController extends Controller {
 	public function __construct(
 		IRequest $request,
 		private KeyService $keys,

lib/Crypto/CryptoException.php

@@ -7,5 +7,5 @@ declare(strict_types=1);
 
 namespace OCA\NgBackup\Crypto;
 
-class CryptoException extends \RuntimeException {
+final class CryptoException extends \RuntimeException {
 }

lib/Db/AppConfigCatalogAnchor.php

@@ -12,7 +12,7 @@ use OCA\NgBackup\Repository\ICatalogAnchor;
 use OCP\IAppConfig;
 
 /** Keeps the newest catalog generation seen per repository in the app config (outside the location). */
-class AppConfigCatalogAnchor implements ICatalogAnchor {
+final class AppConfigCatalogAnchor implements ICatalogAnchor {
 	public function __construct(
 		private IAppConfig $appConfig,
 	) {

lib/Db/DbIndexCache.php

@@ -11,7 +11,7 @@ use OCA\NgBackup\Repository\IIndexCache;
 use OCP\DB\Exception;
 use OCP\IDBConnection;
 
-class DbIndexCache implements IIndexCache {
+final class DbIndexCache implements IIndexCache {
 	public function __construct(
 		private IDBConnection $db,
 	) {

lib/Db/Run.php

@@ -33,7 +33,7 @@ use OCP\AppFramework\Db\Entity;
  * @method int|null getFinishedAt()
  * @method void setFinishedAt(?int $v)
  */
-class Run extends Entity {
+final class Run extends Entity {
 	public const RUNNING = 'running';
 	public const DONE = 'done';
 	public const FAILED = 'failed';

lib/Db/RunMapper.php

@@ -12,7 +12,7 @@ use OCP\DB\QueryBuilder\IQueryBuilder;
 use OCP\IDBConnection;
 
 /** @template-extends QBMapper<Run> */
-class RunMapper extends QBMapper {
+final class RunMapper extends QBMapper {
 	public function __construct(IDBConnection $db) {
 		parent::__construct($db, 'ngb_runs', Run::class);
 	}

lib/Db/Snapshot.php

@@ -25,7 +25,7 @@ use OCP\AppFramework\Db\Entity;
  * @method int|null getBytes()
  * @method void setBytes(?int $v)
  */
-class Snapshot extends Entity {
+final class Snapshot extends Entity {
 	protected int $targetId = 0;
 	protected string $snapshotId = '';
 	protected string $kind = '';

lib/Db/SnapshotMapper.php

@@ -12,7 +12,7 @@ use OCP\DB\QueryBuilder\IQueryBuilder;
 use OCP\IDBConnection;
 
 /** @template-extends QBMapper<Snapshot> */
-class SnapshotMapper extends QBMapper {
+final class SnapshotMapper extends QBMapper {
 	public function __construct(IDBConnection $db) {
 		parent::__construct($db, 'ngb_snapshots', Snapshot::class);
 	}

lib/Db/Target.php

@@ -29,7 +29,7 @@ use OCP\AppFramework\Db\Entity;
  * @method int getCreatedAt()
  * @method void setCreatedAt(int $v)
  */
-class Target extends Entity {
+final class Target extends Entity {
 	protected string $name = '';
 	protected string $backend = '';
 	protected string $auth = '';

lib/Db/TargetMapper.php

@@ -11,7 +11,7 @@ use OCP\AppFramework\Db\QBMapper;
 use OCP\IDBConnection;
 
 /** @template-extends QBMapper<Target> */
-class TargetMapper extends QBMapper {
+final class TargetMapper extends QBMapper {
 	public function __construct(IDBConnection $db) {
 		parent::__construct($db, 'ngb_targets', Target::class);
 	}

lib/Migration/Version000001Date20261002000000.php

@@ -13,7 +13,7 @@ use OCP\DB\Types;
 use OCP\Migration\IOutput;
 use OCP\Migration\SimpleMigrationStep;
 
-class Version000001Date20261002000000 extends SimpleMigrationStep {
+final class Version000001Date20261002000000 extends SimpleMigrationStep {
 	public function changeSchema(IOutput $output, Closure $schemaClosure, array $options): ?ISchemaWrapper {
 		/** @var ISchemaWrapper $schema */
 		$schema = $schemaClosure();

lib/Migration/Version000002Date20261002010000.php

@@ -14,7 +14,7 @@ use OCP\Migration\IOutput;
 use OCP\Migration\SimpleMigrationStep;
 
 /** Local cache of the per-pack index files, so opening a repository does not download them all. */
-class Version000002Date20261002010000 extends SimpleMigrationStep {
+final class Version000002Date20261002010000 extends SimpleMigrationStep {
 	public function changeSchema(IOutput $output, Closure $schemaClosure, array $options): ?ISchemaWrapper {
 		/** @var ISchemaWrapper $schema */
 		$schema = $schemaClosure();

lib/Migration/Version000003Date20261002020000.php

@@ -14,7 +14,7 @@ use OCP\Migration\IOutput;
 use OCP\Migration\SimpleMigrationStep;
 
 /** Append-only locations: NG Backup never deletes anything there (cleanup by the location's own lifecycle rules). */
-class Version000003Date20261002020000 extends SimpleMigrationStep {
+final class Version000003Date20261002020000 extends SimpleMigrationStep {
 	public function changeSchema(IOutput $output, Closure $schemaClosure, array $options): ?ISchemaWrapper {
 		/** @var ISchemaWrapper $schema */
 		$schema = $schemaClosure();

lib/Migration/Version000004Date20261002030000.php

@@ -14,7 +14,7 @@ use OCP\Migration\IOutput;
 use OCP\Migration\SimpleMigrationStep;
 
 /** Optional size limit per location (cost control; S3 has no bucket quota). */
-class Version000004Date20261002030000 extends SimpleMigrationStep {
+final class Version000004Date20261002030000 extends SimpleMigrationStep {
 	public function changeSchema(IOutput $output, Closure $schemaClosure, array $options): ?ISchemaWrapper {
 		/** @var ISchemaWrapper $schema */
 		$schema = $schemaClosure();

lib/Migration/Version000005Date20261002040000.php

@@ -14,7 +14,7 @@ use OCP\Migration\IOutput;
 use OCP\Migration\SimpleMigrationStep;
 
 /** Leases with an expiry: a killed process cannot block a location for longer than its lease. */
-class Version000005Date20261002040000 extends SimpleMigrationStep {
+final class Version000005Date20261002040000 extends SimpleMigrationStep {
 	public function changeSchema(IOutput $output, Closure $schemaClosure, array $options): ?ISchemaWrapper {
 		/** @var ISchemaWrapper $schema */
 		$schema = $schemaClosure();

lib/Notification/Notifier.php

@@ -14,7 +14,7 @@ use OCP\Notification\INotification;
 use OCP\Notification\INotifier;
 use OCP\Notification\UnknownNotificationException;
 
-class Notifier implements INotifier {
+final class Notifier implements INotifier {
 	public function __construct(
 		private IFactory $l10n,
 		private IURLGenerator $url,

lib/Repository/QuotaExceededException.php

@@ -7,5 +7,5 @@ declare(strict_types=1);
 
 namespace OCA\NgBackup\Repository;
 
-class QuotaExceededException extends RepositoryException {
+final class QuotaExceededException extends RepositoryException {
 }

lib/Repository/Repository.php

@@ -345,20 +345,19 @@ final class Repository {
 		$meta = $this->snapshotMeta($snapshotId);
 		$dbInTrash = null;
 		if (isset($meta['db']) && is_string($meta['db']) && $this->backend->exists($meta['db'])) {
+			// Its encryption is bound to its path (object:db/...), which changes on a move, so it
+			// must be decrypted and re-encrypted under the new path, not moved as raw bytes.
 			$dbInTrash = 'trash/' . $meta['db'];
 			$this->putObject($dbInTrash, $this->getObject($meta['db']));
+			$this->backend->delete($meta['db']);
 		}
-		// The snapshot object is bound to its id (not its path), so it can be copied as-is.
-		$this->backend->put('trash/snapshots/' . $snapshotId, $this->backend->get('snapshots/' . $snapshotId));
+		// The snapshot object is bound to its id (not its path), so it can be moved as raw bytes.
+		$this->backend->move('snapshots/' . $snapshotId, 'trash/snapshots/' . $snapshotId);
 		$this->putObject('trash/info/' . $snapshotId, json_encode(['forgottenAt' => time(), 'by' => $by, 'db' => $meta['db'] ?? null,
 			'dbInTrash' => $dbInTrash, 'time' => $meta['time'] ?? null, 'label' => $meta['label'] ?? ''], JSON_THROW_ON_ERROR));
 		unset($this->catalog->snapshots[$snapshotId]);
 		$this->catalog->trash[$snapshotId] = true;
 		$this->catalog->write();
-		if ($dbInTrash !== null) {
-			$this->backend->delete($meta['db']);
-		}
-		$this->backend->delete('snapshots/' . $snapshotId);
 	}
 
 	/** Undo forget(): move a snapshot back from the trash. */
@@ -368,11 +367,10 @@ final class Repository {
 			$this->putObject($info['db'], $this->getObject($info['dbInTrash']));
 			$this->backend->delete($info['dbInTrash']);
 		}
-		$this->backend->put('snapshots/' . $snapshotId, $this->backend->get('trash/snapshots/' . $snapshotId));
+		$this->backend->move('trash/snapshots/' . $snapshotId, 'snapshots/' . $snapshotId);
 		$this->catalog->snapshots[$snapshotId] = true;
 		unset($this->catalog->trash[$snapshotId]);
 		$this->catalog->write();
-		$this->backend->delete('trash/snapshots/' . $snapshotId);
 		$this->backend->delete('trash/info/' . $snapshotId);
 	}
 

lib/Service/AlertService.php

@@ -15,7 +15,7 @@ use OCP\IGroupManager;
 use OCP\Notification\IManager;
 
 /** Notifies administrators about failed runs and locations without a recent successful backup. */
-class AlertService {
+final class AlertService {
 	public const STALE_AFTER = 2 * 86400;
 
 	public function __construct(

lib/Service/BackupService.php

@@ -28,7 +28,7 @@ use Psr\Log\LoggerInterface;
  * Excluded by default: previews, log files, the updater's backups and each user's cache and
  * temporary uploads (all regenerable or temporary).
  */
-class BackupService {
+final class BackupService {
 	public const KIND_FULL = 'full';
 
 	public function __construct(

lib/Service/KeyService.php

@@ -22,7 +22,7 @@ use OCP\Security\ICrypto;
  *   into the recovery kit, so backups can be restored on a fresh server with the passphrase.
  * - The admin must confirm having stored the recovery kit before the first backup runs.
  */
-class KeyService {
+final class KeyService {
 	private const KEY_MASTER = 'master_key';
 	private const KEY_WRAPPED = 'master_key_wrapped';
 	private const KEY_CONFIRMED = 'recovery_kit_confirmed';

lib/Service/KeySlotService.php

@@ -13,7 +13,7 @@ namespace OCA\NgBackup\Service;
  * is written to all locations and announced to all administrators; a new recovery kit must be
  * downloaded and confirmed afterwards (backups keep running meanwhile).
  */
-class KeySlotService {
+final class KeySlotService {
 	public function __construct(
 		private KeyService $keys,
 		private TargetService $targets,

lib/Service/LeaseService.php

@@ -19,7 +19,7 @@ use OCP\Lock\LockedException;
  * holder keeps refreshing it. Nextcloud's lock is only held for the few milliseconds in which a
  * lease is checked and written.
  */
-class LeaseService {
+final class LeaseService {
 	public const SHARED = 's';
 	public const EXCLUSIVE = 'x';
 

lib/Service/PruneService.php

@@ -20,7 +20,7 @@ use OCP\Lock\LockedException;
  * prunes data no remaining snapshot uses. Never runs on append-only locations, never while a
  * backup to the same location is running (the location lock is shared with BackupService).
  */
-class PruneService {
+final class PruneService {
 	public function __construct(
 		private TargetService $targets,
 		private RunMapper $runs,

lib/Service/RestoreService.php

@@ -28,7 +28,7 @@ use OCP\Files\NotFoundException;
  *  - merge:   into the original place, existing files are overwritten (old content kept as a version)
  *  - replace: like merge, and files that are not in the snapshot are moved to the trash
  */
-class RestoreService {
+final class RestoreService {
 	public const MODE_NEW_FOLDER = 'new-folder';
 	public const MODE_MERGE = 'merge';
 	public const MODE_REPLACE = 'replace';

lib/Service/TargetService.php

@@ -22,7 +22,7 @@ use OCP\Server;
  * object is built only while it is used; nothing is mounted. files_external is loaded for its
  * classes but its enabled/disabled state is left as the admin set it.
  */
-class TargetService {
+final class TargetService {
 	public function __construct(
 		private TargetMapper $mapper,
 		private KeyService $keys,

lib/Settings/Admin.php

@@ -11,7 +11,7 @@ use OCP\AppFramework\Http\TemplateResponse;
 use OCP\Settings\ISettings;
 use OCP\Util;
 
-class Admin implements ISettings {
+final class Admin implements ISettings {
 	public function getForm(): TemplateResponse {
 		Util::addScript('ng_backup', 'ng_backup-admin');
 		Util::addStyle('ng_backup', 'ng_backup-admin');

lib/Settings/AdminSection.php

@@ -11,7 +11,7 @@ use OCP\IL10N;
 use OCP\IURLGenerator;
 use OCP\Settings\IIconSection;
 
-class AdminSection implements IIconSection {
+final class AdminSection implements IIconSection {
 	public function __construct(
 		private IL10N $l,
 		private IURLGenerator $url,

lib/SetupCheck/BackupStatusCheck.php

@@ -19,7 +19,7 @@ use OCP\SetupCheck\ISetupCheck;
 use OCP\SetupCheck\SetupResult;
 
 /** Shows the backup state in the admin overview (Security & setup warnings). */
-class BackupStatusCheck implements ISetupCheck {
+final class BackupStatusCheck implements ISetupCheck {
 	public function __construct(
 		private IL10N $l,
 		private IURLGenerator $url,

lib/UserMigration/RepositoryImportSource.php

@@ -8,6 +8,7 @@ declare(strict_types=1);
 namespace OCA\NgBackup\UserMigration;
 
 use OCA\NgBackup\Repository\Repository;
+use OCP\Files\File;
 use OCP\Files\Folder;
 use OCP\UserMigration\IImportSource;
 use OCP\UserMigration\UserMigrationException;
@@ -30,10 +31,14 @@ final class RepositoryImportSource implements IImportSource {
 		return $data;
 	}
 
+	/** @return resource */
 	public function getFileAsStream(string $path) {
 		$entry = $this->entry($path, 'f');
 		// Phase 0: buffer in php://temp (memory up to 8 MiB, then a temp file for this one file).
 		$stream = fopen('php://temp/maxmemory:' . (8 * 1048576), 'w+b');
+		if ($stream === false) {
+			throw new UserMigrationException('Cannot buffer ' . $path);
+		}
 		foreach ($this->repo->readBlobs($entry['b']) as $data) {
 			for ($done = 0, $len = strlen($data); $done < $len; $done += $n) {
 				$n = fwrite($stream, $done === 0 ? $data : substr($data, $done));
@@ -51,6 +56,7 @@ final class RepositoryImportSource implements IImportSource {
 		$prefix = trim($path, '/');
 		$prefix = $prefix === '' ? '' : $prefix . '/';
 		$names = [];
+		/** @var string $p */
 		foreach (array_keys($this->manifest['entries']) as $p) {
 			if ($prefix === '' || str_starts_with($p, $prefix)) {
 				$rest = substr($p, strlen($prefix));
@@ -70,6 +76,7 @@ final class RepositoryImportSource implements IImportSource {
 		if (isset($this->manifest['entries'][$p])) {
 			return true;
 		}
+		/** @var string $k */
 		foreach (array_keys($this->manifest['entries']) as $k) {
 			if (str_starts_with($k, $p . '/')) {
 				return true;
@@ -91,12 +98,17 @@ final class RepositoryImportSource implements IImportSource {
 				$this->copyToFolder($sub, $path);
 			} else {
 				$stream = $this->getFileAsStream($path);
-				if ($destination->nodeExists($name)) {
-					$destination->get($name)->putContent($stream);
-				} else {
-					$destination->newFile($name, $stream);
-				}
-				if (is_resource($stream)) {
+				try {
+					if ($destination->nodeExists($name)) {
+						$existing = $destination->get($name);
+						if (!$existing instanceof File) {
+							throw new UserMigrationException("$path exists and is not a file");
+						}
+						$existing->putContent($stream);
+					} else {
+						$destination->newFile($name, $stream);
+					}
+				} finally {
 					fclose($stream);
 				}
 			}

psalm-baseline.xml

@@ -0,0 +1,497 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<files psalm-version="6.19.1@e2ca44251c1f1aa2e35452d426895746b47de64e">
+  <file src="lib/Backend/ExternalStorageFactory.php">
+    <MissingClosureParamType>
+      <code><![CDATA[$p]]></code>
+      <code><![CDATA[$p]]></code>
+    </MissingClosureParamType>
+    <MissingClosureReturnType>
+      <code><![CDATA[fn ($p) => $p->jsonSerialize()]]></code>
+      <code><![CDATA[fn ($p) => $p->jsonSerialize()]]></code>
+    </MissingClosureReturnType>
+  </file>
+  <file src="lib/Backend/IBackend.php">
+    <MissingParamType>
+      <code><![CDATA[$stream]]></code>
+    </MissingParamType>
+  </file>
+  <file src="lib/Backend/LocalBackend.php">
+    <MissingParamType>
+      <code><![CDATA[$stream]]></code>
+    </MissingParamType>
+    <TypeDoesNotContainType>
+      <code><![CDATA[$out !== false]]></code>
+    </TypeDoesNotContainType>
+  </file>
+  <file src="lib/Backend/StorageBackend.php">
+    <MissingParamType>
+      <code><![CDATA[$stream]]></code>
+    </MissingParamType>
+  </file>
+  <file src="lib/BackgroundJob/BackupJob.php">
+    <MissingParamType>
+      <code><![CDATA[$argument]]></code>
+    </MissingParamType>
+  </file>
+  <file src="lib/BackgroundJob/RestoreJob.php">
+    <MissingParamType>
+      <code><![CDATA[$argument]]></code>
+    </MissingParamType>
+  </file>
+  <file src="lib/Command/Browse.php">
+    <InvalidOperand>
+      <code><![CDATA[$b /= 1024]]></code>
+    </InvalidOperand>
+  </file>
+  <file src="lib/Command/KeyConfirm.php">
+    <UndefinedInterfaceMethod>
+      <code><![CDATA[ask]]></code>
+      <code><![CDATA[ask]]></code>
+    </UndefinedInterfaceMethod>
+  </file>
+  <file src="lib/Command/KeyInit.php">
+    <UndefinedInterfaceMethod>
+      <code><![CDATA[ask]]></code>
+      <code><![CDATA[ask]]></code>
+    </UndefinedInterfaceMethod>
+  </file>
+  <file src="lib/Command/KeySlots.php">
+    <UndefinedInterfaceMethod>
+      <code><![CDATA[ask]]></code>
+      <code><![CDATA[ask]]></code>
+    </UndefinedInterfaceMethod>
+  </file>
+  <file src="lib/Command/Prune.php">
+    <PossiblyFalseOperand>
+      <code><![CDATA[json_encode($this->prune->policy()->toArray())]]></code>
+    </PossiblyFalseOperand>
+  </file>
+  <file src="lib/Command/RunBackup.php">
+    <PossiblyNullArgument>
+      <code><![CDATA[$run->getSnapshotId()]]></code>
+    </PossiblyNullArgument>
+  </file>
+  <file src="lib/Command/Status.php">
+    <RiskyTruthyFalsyComparison>
+      <code><![CDATA[$c]]></code>
+      <code><![CDATA[$r->getFinishedAt()]]></code>
+    </RiskyTruthyFalsyComparison>
+  </file>
+  <file src="lib/Command/TargetAdd.php">
+    <PossiblyNullArgument>
+      <code><![CDATA[$r['target']->getRepositoryId()]]></code>
+    </PossiblyNullArgument>
+    <PossiblyUndefinedArrayOffset>
+      <code><![CDATA[$v]]></code>
+    </PossiblyUndefinedArrayOffset>
+  </file>
+  <file src="lib/Command/TargetBackends.php">
+    <UndefinedClass>
+      <code><![CDATA[Base]]></code>
+    </UndefinedClass>
+  </file>
+  <file src="lib/Command/TargetLimit.php">
+    <InvalidOperand>
+      <code><![CDATA[(float)$m[1] * $factor]]></code>
+    </InvalidOperand>
+  </file>
+  <file src="lib/Command/TargetList.php">
+    <UndefinedClass>
+      <code><![CDATA[Base]]></code>
+    </UndefinedClass>
+  </file>
+  <file src="lib/Command/TargetTrustCurrent.php">
+    <UndefinedInterfaceMethod>
+      <code><![CDATA[ask]]></code>
+    </UndefinedInterfaceMethod>
+  </file>
+  <file src="lib/Command/Trash.php">
+    <RedundantCastGivenDocblockType>
+      <code><![CDATA[(string)($info['time'] ?? '')]]></code>
+    </RedundantCastGivenDocblockType>
+  </file>
+  <file src="lib/Controller/AdminApiController.php">
+    <InvalidOperand>
+      <code><![CDATA[$maxGb * 1073741824]]></code>
+      <code><![CDATA[$maxGb * 1073741824]]></code>
+    </InvalidOperand>
+    <PossiblyNullArgument>
+      <code><![CDATA[$r->getSnapshotId()]]></code>
+    </PossiblyNullArgument>
+  </file>
+  <file src="lib/Crypto/StreamCipher.php">
+    <MissingParamType>
+      <code><![CDATA[$in]]></code>
+      <code><![CDATA[$out]]></code>
+    </MissingParamType>
+    <PossiblyFalseArgument>
+      <code><![CDATA[$in]]></code>
+      <code><![CDATA[$in]]></code>
+      <code><![CDATA[$in]]></code>
+      <code><![CDATA[$in]]></code>
+      <code><![CDATA[$in]]></code>
+      <code><![CDATA[$in]]></code>
+      <code><![CDATA[$out]]></code>
+      <code><![CDATA[$out]]></code>
+      <code><![CDATA[$out]]></code>
+      <code><![CDATA[$out]]></code>
+      <code><![CDATA[$out]]></code>
+      <code><![CDATA[$out]]></code>
+    </PossiblyFalseArgument>
+    <PossiblyInvalidArrayAccess>
+      <code><![CDATA[unpack('N', $len)[1]]]></code>
+    </PossiblyInvalidArrayAccess>
+  </file>
+  <file src="lib/Db/AppConfigCatalogAnchor.php">
+    <PossiblyFalseArgument>
+      <code><![CDATA[json_encode(['gen' => $gen, 'hash' => $hash])]]></code>
+    </PossiblyFalseArgument>
+  </file>
+  <file src="lib/Db/DbDumper.php">
+    <InvalidArrayOffset>
+      <code><![CDATA[$info['sha256']]]></code>
+      <code><![CDATA[$manifest['sequences']]]></code>
+    </InvalidArrayOffset>
+    <MissingClosureReturnType>
+      <code><![CDATA[fn ($c) => $end[array_search($c, $columns, true)]]]></code>
+      <code><![CDATA[fn ($c) => $q($c)]]></code>
+      <code><![CDATA[fn (string $c) => $this->db->quoteIdentifier($c)]]></code>
+      <code><![CDATA[fn (string $c) => $this->db->quoteIdentifier($c)]]></code>
+    </MissingClosureReturnType>
+    <PossiblyFalseArgument>
+      <code><![CDATA[$value]]></code>
+    </PossiblyFalseArgument>
+    <PossiblyNullArgument>
+      <code><![CDATA[$columns]]></code>
+    </PossiblyNullArgument>
+    <UndefinedClass>
+      <code><![CDATA[$this->db]]></code>
+      <code><![CDATA[$this->db]]></code>
+      <code><![CDATA[$this->db]]></code>
+      <code><![CDATA[$this->db]]></code>
+      <code><![CDATA[$this->db]]></code>
+      <code><![CDATA[$this->db]]></code>
+      <code><![CDATA[$this->db]]></code>
+      <code><![CDATA[$this->db]]></code>
+      <code><![CDATA[$this->db]]></code>
+      <code><![CDATA[$this->db]]></code>
+      <code><![CDATA[$this->db]]></code>
+      <code><![CDATA[$this->db]]></code>
+      <code><![CDATA[$this->db]]></code>
+      <code><![CDATA[$this->db]]></code>
+      <code><![CDATA[$this->db]]></code>
+      <code><![CDATA[$this->db]]></code>
+      <code><![CDATA[$this->db]]></code>
+      <code><![CDATA[$this->db]]></code>
+      <code><![CDATA[$this->db]]></code>
+      <code><![CDATA[TransactionIsolationLevel]]></code>
+      <code><![CDATA[\Doctrine\DBAL\ParameterType]]></code>
+      <code><![CDATA[\Doctrine\DBAL\ParameterType]]></code>
+      <code><![CDATA[\Doctrine\DBAL\ParameterType]]></code>
+      <code><![CDATA[\Doctrine\DBAL\Platforms\PostgreSQLPlatform]]></code>
+      <code><![CDATA[\Doctrine\DBAL\Platforms\PostgreSQLPlatform]]></code>
+      <code><![CDATA[\Doctrine\DBAL\Platforms\PostgreSQLPlatform]]></code>
+      <code><![CDATA[\Doctrine\DBAL\Schema\Table]]></code>
+      <code><![CDATA[\Doctrine\DBAL\Schema\Table]]></code>
+      <code><![CDATA[\Doctrine\DBAL\Schema\Table]]></code>
+      <code><![CDATA[private]]></code>
+    </UndefinedClass>
+  </file>
+  <file src="lib/Db/Run.php">
+    <PropertyNotSetInConstructor>
+      <code><![CDATA[Run]]></code>
+    </PropertyNotSetInConstructor>
+  </file>
+  <file src="lib/Db/Snapshot.php">
+    <PropertyNotSetInConstructor>
+      <code><![CDATA[Snapshot]]></code>
+    </PropertyNotSetInConstructor>
+  </file>
+  <file src="lib/Db/Target.php">
+    <PropertyNotSetInConstructor>
+      <code><![CDATA[Target]]></code>
+    </PropertyNotSetInConstructor>
+  </file>
+  <file src="lib/Job/BackupRun.php">
+    <ArgumentTypeCoercion>
+      <code><![CDATA[$blobs]]></code>
+    </ArgumentTypeCoercion>
+    <MissingParamType>
+      <code><![CDATA[$fh]]></code>
+    </MissingParamType>
+    <PossiblyNullIterator>
+      <code><![CDATA[$segments]]></code>
+    </PossiblyNullIterator>
+    <PossiblyUndefinedArrayOffset>
+      <code><![CDATA[$mtime]]></code>
+      <code><![CDATA[$state['cur']]]></code>
+      <code><![CDATA[$state['phase']]]></code>
+      <code><![CDATA[$state['segments']]]></code>
+      <code><![CDATA[$state['stats']]]></code>
+    </PossiblyUndefinedArrayOffset>
+  </file>
+  <file src="lib/Job/ParentCursor.php">
+    <PossiblyNullReference>
+      <code><![CDATA[next]]></code>
+    </PossiblyNullReference>
+  </file>
+  <file src="lib/Job/TreeWalker.php">
+    <RedundantCastGivenDocblockType>
+      <code><![CDATA[(string)$name]]></code>
+    </RedundantCastGivenDocblockType>
+  </file>
+  <file src="lib/Migration/Version000001Date20261002000000.php">
+    <UndefinedDocblockClass>
+      <code><![CDATA[$schema->createTable('ngb_targets')]]></code>
+      <code><![CDATA[$t]]></code>
+      <code><![CDATA[$t]]></code>
+      <code><![CDATA[$t]]></code>
+      <code><![CDATA[$t]]></code>
+      <code><![CDATA[$t]]></code>
+      <code><![CDATA[$t]]></code>
+      <code><![CDATA[$t]]></code>
+      <code><![CDATA[$t]]></code>
+      <code><![CDATA[$t]]></code>
+      <code><![CDATA[$t]]></code>
+      <code><![CDATA[$t]]></code>
+      <code><![CDATA[$t]]></code>
+      <code><![CDATA[$t]]></code>
+      <code><![CDATA[$t]]></code>
+      <code><![CDATA[$t]]></code>
+      <code><![CDATA[$t]]></code>
+      <code><![CDATA[$t]]></code>
+      <code><![CDATA[$t]]></code>
+      <code><![CDATA[$t]]></code>
+      <code><![CDATA[$t]]></code>
+      <code><![CDATA[$t]]></code>
+      <code><![CDATA[$t]]></code>
+      <code><![CDATA[$t]]></code>
+      <code><![CDATA[$t]]></code>
+      <code><![CDATA[$t]]></code>
+      <code><![CDATA[$t]]></code>
+      <code><![CDATA[$t]]></code>
+      <code><![CDATA[$t]]></code>
+      <code><![CDATA[$t]]></code>
+      <code><![CDATA[$t]]></code>
+      <code><![CDATA[$t]]></code>
+      <code><![CDATA[$t]]></code>
+      <code><![CDATA[$t]]></code>
+      <code><![CDATA[$t]]></code>
+    </UndefinedDocblockClass>
+  </file>
+  <file src="lib/Migration/Version000002Date20261002010000.php">
+    <UndefinedDocblockClass>
+      <code><![CDATA[$t]]></code>
+      <code><![CDATA[$t]]></code>
+      <code><![CDATA[$t]]></code>
+      <code><![CDATA[$t]]></code>
+      <code><![CDATA[$t]]></code>
+      <code><![CDATA[$t]]></code>
+    </UndefinedDocblockClass>
+  </file>
+  <file src="lib/Migration/Version000003Date20261002020000.php">
+    <UndefinedDocblockClass>
+      <code><![CDATA[$schema->getTable('ngb_targets')]]></code>
+      <code><![CDATA[$t]]></code>
+      <code><![CDATA[$t]]></code>
+    </UndefinedDocblockClass>
+  </file>
+  <file src="lib/Migration/Version000004Date20261002030000.php">
+    <UndefinedDocblockClass>
+      <code><![CDATA[$t]]></code>
+      <code><![CDATA[$t]]></code>
+    </UndefinedDocblockClass>
+  </file>
+  <file src="lib/Migration/Version000005Date20261002040000.php">
+    <UndefinedDocblockClass>
+      <code><![CDATA[$t]]></code>
+      <code><![CDATA[$t]]></code>
+      <code><![CDATA[$t]]></code>
+      <code><![CDATA[$t]]></code>
+      <code><![CDATA[$t]]></code>
+      <code><![CDATA[$t]]></code>
+    </UndefinedDocblockClass>
+  </file>
+  <file src="lib/Repository/BlobIndex.php">
+    <PossiblyFalseArgument>
+      <code><![CDATA[$stream]]></code>
+      <code><![CDATA[$stream]]></code>
+    </PossiblyFalseArgument>
+  </file>
+  <file src="lib/Repository/Catalog.php">
+    <PossiblyFalseArgument>
+      <code><![CDATA[$stream]]></code>
+      <code><![CDATA[$stream]]></code>
+    </PossiblyFalseArgument>
+  </file>
+  <file src="lib/Repository/PackWriter.php">
+    <InvalidPropertyAssignmentValue>
+      <code><![CDATA[$this->buffer]]></code>
+    </InvalidPropertyAssignmentValue>
+    <PossiblyFalsePropertyAssignmentValue>
+      <code><![CDATA[fopen('php://temp/maxmemory:' . ($this->targetSize + 8 * 1048576), 'w+b')]]></code>
+    </PossiblyFalsePropertyAssignmentValue>
+    <RedundantPropertyInitializationCheck>
+      <code><![CDATA[isset($this->buffer)]]></code>
+    </RedundantPropertyInitializationCheck>
+  </file>
+  <file src="lib/Repository/Repository.php">
+    <InvalidOperand>
+      <code><![CDATA[strlen($data) * 0.95]]></code>
+    </InvalidOperand>
+    <InvalidReturnStatement>
+      <code><![CDATA[['snapshot' => $snapshotId] + $stats]]></code>
+    </InvalidReturnStatement>
+    <InvalidReturnType>
+      <code><![CDATA[array{snapshot:string, files:int, reused:int, read:int, newBlobs:int, dupBlobs:int, uploaded:int}]]></code>
+    </InvalidReturnType>
+    <MissingParamType>
+      <code><![CDATA[$fh]]></code>
+    </MissingParamType>
+    <PossiblyFalseArgument>
+      <code><![CDATA[$encrypted]]></code>
+      <code><![CDATA[$encrypted]]></code>
+      <code><![CDATA[$encrypted]]></code>
+      <code><![CDATA[$encrypted]]></code>
+      <code><![CDATA[$fh]]></code>
+      <code><![CDATA[$plain]]></code>
+      <code><![CDATA[$plain]]></code>
+      <code><![CDATA[$plain]]></code>
+      <code><![CDATA[$plain]]></code>
+      <code><![CDATA[$plain]]></code>
+      <code><![CDATA[$plain]]></code>
+      <code><![CDATA[$plain]]></code>
+      <code><![CDATA[$plain]]></code>
+      <code><![CDATA[$plain]]></code>
+      <code><![CDATA[$s]]></code>
+      <code><![CDATA[$s]]></code>
+      <code><![CDATA[$tree]]></code>
+      <code><![CDATA[$tree]]></code>
+      <code><![CDATA[$tree]]></code>
+      <code><![CDATA[$tree]]></code>
+      <code><![CDATA[$tree]]></code>
+      <code><![CDATA[$tree]]></code>
+      <code><![CDATA[$tree]]></code>
+      <code><![CDATA[$tree]]></code>
+      <code><![CDATA[$tree]]></code>
+      <code><![CDATA[$tree]]></code>
+    </PossiblyFalseArgument>
+    <PossiblyUndefinedArrayOffset>
+      <code><![CDATA[$stats['files']]]></code>
+      <code><![CDATA[$stats['reused']]]></code>
+    </PossiblyUndefinedArrayOffset>
+    <PropertyNotSetInConstructor>
+      <code><![CDATA[$catalog]]></code>
+    </PropertyNotSetInConstructor>
+  </file>
+  <file src="lib/Service/AlertService.php">
+    <InvalidOperand>
+      <code><![CDATA[$bytes / $limit * 100]]></code>
+      <code><![CDATA[0.8 * $limit]]></code>
+    </InvalidOperand>
+    <PossiblyFalseOperand>
+      <code><![CDATA[json_encode(array_diff_key($params, ['actor' => 1]), JSON_UNESCAPED_SLASHES)]]></code>
+    </PossiblyFalseOperand>
+  </file>
+  <file src="lib/Service/BackupService.php">
+    <InvalidOperand>
+      <code><![CDATA[$deadline - microtime(true) + 120]]></code>
+    </InvalidOperand>
+    <UndefinedClass>
+      <code><![CDATA[\OC]]></code>
+      <code><![CDATA[\OC]]></code>
+    </UndefinedClass>
+    <UndefinedInterfaceMethod>
+      <code><![CDATA[getInner]]></code>
+    </UndefinedInterfaceMethod>
+  </file>
+  <file src="lib/Service/KeyService.php">
+    <ArgumentTypeCoercion>
+      <code><![CDATA[array_diff(range(1, self::MAX_SLOTS), $used)]]></code>
+    </ArgumentTypeCoercion>
+    <InvalidReturnStatement>
+      <code><![CDATA[[
+			'version' => 1,
+			'app' => 'NG Backup',
+			'fingerprint' => $this->fingerprint(),
+			'kit_version' => $this->kitVersion(),
+			'confirmation_code' => $this->kitCode(),
+			'created' => gmdate('c'),
+			'wrapped_key' => $this->wrappedKey(),
+			'slots' => $this->slots(),
+			'instructions' => 'Keep this file safe, outside this server. Any one of the passphrases of the slots listed here opens it. '
+				. 'To restore on a new server: install NG Backup, add the backup location and enter this kit with one passphrase. '
+				. 'Without the kit (or the location) and a passphrase, the backups cannot be decrypted.',
+		]]]></code>
+    </InvalidReturnStatement>
+    <InvalidReturnType>
+      <code><![CDATA[array{version:int, app:string, fingerprint:string, created:string, wrapped_key:array, instructions:string}]]></code>
+    </InvalidReturnType>
+    <LessSpecificReturnStatement>
+      <code><![CDATA[array_map(fn ($s) => ['slot' => $s['slot'], 'label' => $s['label'], 'created' => $s['created']], $this->wrappedKey()['slots'])]]></code>
+    </LessSpecificReturnStatement>
+    <MissingClosureParamType>
+      <code><![CDATA[$s]]></code>
+      <code><![CDATA[$s]]></code>
+    </MissingClosureParamType>
+    <MissingClosureReturnType>
+      <code><![CDATA[static fn (string $c) => strtoupper(preg_replace('/[^A-Za-z0-9]/', '', $c) ?? '')]]></code>
+    </MissingClosureReturnType>
+    <MoreSpecificReturnType>
+      <code><![CDATA[list<array{slot:int, label:string, created:int}>]]></code>
+    </MoreSpecificReturnType>
+    <PossiblyFalseArgument>
+      <code><![CDATA[base64_decode($this->crypto->decrypt($enc), true)]]></code>
+    </PossiblyFalseArgument>
+  </file>
+  <file src="lib/Service/PruneService.php">
+    <LessSpecificReturnStatement>
+      <code><![CDATA[['kept' => $keep, 'forgotten' => $forget, 'purged' => $purged, 'prune' => $prune]]]></code>
+    </LessSpecificReturnStatement>
+    <MissingClosureReturnType>
+      <code><![CDATA[fn () => $fn()]]></code>
+    </MissingClosureReturnType>
+    <MoreSpecificReturnType>
+      <code><![CDATA[array{kept: array<string, list<string>>, forgotten: list<string>, purged: list<string>, prune: array}]]></code>
+    </MoreSpecificReturnType>
+  </file>
+  <file src="lib/Service/RestoreService.php">
+    <LessSpecificReturnStatement>
+      <code><![CDATA[array_values($children)]]></code>
+    </LessSpecificReturnStatement>
+    <MissingDependency>
+      <code><![CDATA[$this->root]]></code>
+      <code><![CDATA[private]]></code>
+    </MissingDependency>
+    <MoreSpecificReturnType>
+      <code><![CDATA[list<array{name:string, type:string, size:int, mtime:int|null, files:int}>]]></code>
+    </MoreSpecificReturnType>
+    <PossiblyFalseArgument>
+      <code><![CDATA[$in]]></code>
+      <code><![CDATA[$out]]></code>
+      <code><![CDATA[$out]]></code>
+    </PossiblyFalseArgument>
+    <PossiblyNullArrayOffset>
+      <code><![CDATA[$children]]></code>
+      <code><![CDATA[$children]]></code>
+    </PossiblyNullArrayOffset>
+    <RedundantCastGivenDocblockType>
+      <code><![CDATA[(string)$relPath]]></code>
+      <code><![CDATA[(string)$relPath]]></code>
+    </RedundantCastGivenDocblockType>
+  </file>
+  <file src="lib/Service/TargetService.php">
+    <InvalidReturnStatement>
+      <code><![CDATA[$this->factory()->describeBackends()]]></code>
+    </InvalidReturnStatement>
+    <InvalidReturnType>
+      <code><![CDATA[list<array{id:string, name:string, auth:list<string>, parameters:array}>]]></code>
+    </InvalidReturnType>
+    <UndefinedDocblockClass>
+      <code><![CDATA[Server::get(\OCA\Files_External\Service\BackendService::class)]]></code>
+    </UndefinedDocblockClass>
+    <UnresolvableInclude>
+      <code><![CDATA[require_once $path . '/composer/autoload.php']]></code>
+    </UnresolvableInclude>
+  </file>
+</files>

psalm.xml

@@ -0,0 +1,45 @@
+<?xml version="1.0"?>
+<!-- SPDX-FileCopyrightText: 2026 Dillard Blom -->
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
+<psalm
+    errorLevel="2"
+    resolveFromConfigFile="true"
+    findUnusedBaselineEntry="true"
+    findUnusedCode="false"
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xmlns="https://getpsalm.org/schema/config"
+    xsi:schemaLocation="https://getpsalm.org/schema/config vendor/vimeo/psalm/config.xsd"
+    errorBaseline="psalm-baseline.xml"
+>
+    <projectFiles>
+        <directory name="lib" />
+        <ignoreFiles>
+            <directory name="vendor" />
+        </ignoreFiles>
+    </projectFiles>
+
+    <!-- Interface-only stubs for Nextcloud's public API, not autoloaded at runtime: scanned for
+         type resolution only, never reported on. lib/ must only use OCP\, never internal OC\
+         classes, since those differ between the supported Nextcloud versions (PLAN.md section 6). -->
+    <extraFiles>
+        <directory name="vendor/nextcloud/ocp/OCP" />
+        <directory name="vendor/nextcloud/ocp/NCU" />
+    </extraFiles>
+
+    <issueHandlers>
+        <UndefinedClass>
+            <errorLevel type="suppress">
+                <!-- Provided by files_external at runtime; not a composer dependency (PLAN.md 3.5). -->
+                <referencedClass name="OCA\Files_External\**" />
+            </errorLevel>
+        </UndefinedClass>
+        <!-- The #[\Override] attribute convention (PHP 8.3+) adds no behaviour; this app supports
+             PHP 8.1+, and applying it to every interface-implementing method project-wide is pure
+             ceremony with no bug-catching value, so it's suppressed rather than papered over. -->
+        <MissingOverrideAttribute>
+            <errorLevel type="suppress">
+                <directory name="lib" />
+            </errorLevel>
+        </MissingOverrideAttribute>
+    </issueHandlers>
+</psalm>

tests/integration/roundtrip.sh

@@ -1,9 +1,12 @@
 #!/bin/bash
 # End-to-end round trip of NG Backup inside a Nextcloud installation (CI and local matrix).
-# Usage: roundtrip.sh "<command prefix to run occ/php as the web user in the instance>" <datadir> <apps-path>
+# Usage: roundtrip.sh "<command prefix to run occ/php as the web user in the instance>" <datadir> <apps-path> [target-args]
 #   e.g. roundtrip.sh "docker exec -u www-data ngb-nc35-pgsql" /var/www/html/data /var/www/html/custom_apps
+#   target-args defaults to a local files_external location; pass backend/auth/options to exercise
+#   a different backend (e.g. amazons3 or sftp), see tests/integration/targets-matrix.sh.
 set -euo pipefail
 X="$1"; DATA="$2"; APPS="$3"
+TARGET_ARGS="${4:-local -a null::null -o datadir=/tmp/ngb-rt-target}"
 occ() { $X php occ "$@"; }
 fail() { echo "FAIL: $*"; exit 1; }
 ok() { echo "ok   $*"; }
@@ -17,8 +20,8 @@ CODE=$(occ backup:key:kit | php -r 'echo json_decode(stream_get_contents(STDIN),
 occ backup:key:confirm -u admin --code="$CODE" --confirm="Yes, I confirm" >/dev/null || fail "confirm"
 ok "key, kit code and confirmation"
 
-occ backup:target:add ci local -a null::null -o datadir=/tmp/ngb-rt-target --path=repo >/dev/null || fail "target add"
-ok "local location added"
+occ backup:target:add ci $TARGET_ARGS --path=repo >/dev/null || fail "target add"
+ok "location added"
 
 # Test data: a user with files.
 $X sh -c "OC_PASS='Roundtrip-pw-2026' php occ user:add --password-from-env $U >/dev/null"

tests/integration/targets-matrix.sh

@@ -0,0 +1,65 @@
+#!/bin/bash
+# Round trip of NG Backup against real S3 (s3mock) and SFTP backends, through files_external's own
+# backend/auth classes, same as a production location would use. Backend correctness does not
+# depend on the Nextcloud version or database, so this runs once (not matrixed across NC/DB),
+# on a recent Nextcloud with sqlite. Each backend gets its own fresh Nextcloud container, since
+# NG Backup's key can only be initialised once per instance.
+# Usage: tests/integration/targets-matrix.sh [nextcloud-version]
+set -euo pipefail
+V=${1:-35}
+APP=$(cd "$(dirname "$0")/../.." && pwd)
+NET=ngb-targets-net
+RESULTS=()
+
+cleanup() { docker rm -fv ngb-targets-nc-s3 ngb-targets-nc-sftp ngb-targets-s3 ngb-targets-sftp >/dev/null 2>&1; docker network rm "$NET" >/dev/null 2>&1; }
+trap cleanup EXIT
+
+wait_tcp() { # host port
+  docker run --rm --network "$NET" alpine:3 sh -c "for i in \$(seq 1 30); do nc -z $1 $2 2>/dev/null && exit 0; sleep 1; done; exit 1" \
+    || { echo "FAIL: $1:$2 never came up"; exit 1; }
+}
+
+start_nc() { # container-name
+  docker run -d --name "$1" --network "$NET" \
+    -e NEXTCLOUD_ADMIN_USER=admin -e NEXTCLOUD_ADMIN_PASSWORD=admin-targets-pw -e NEXTCLOUD_TRUSTED_DOMAINS=localhost \
+    -e SQLITE_DATABASE=nextcloud \
+    -v "$APP:/var/www/html/custom_apps/ng_backup:ro" nextcloud:$V-apache >/dev/null
+  for i in $(seq 1 90); do docker exec -u www-data "$1" php occ status 2>/dev/null | grep -q "installed: true" && break; sleep 4; done
+  docker exec "$1" chown www-data:www-data /var/www/html/custom_apps
+  echo "=== NC $V / sqlite ($1): $(docker exec -u www-data "$1" php occ -V 2>/dev/null)"
+}
+
+run() { # label, nc-container, target-args
+  echo "=== $1"
+  if bash ${NGB_TRACE:+-x} "$APP/tests/integration/roundtrip.sh" "docker exec -u www-data $2" /var/www/html/data /var/www/html/custom_apps "$3"; then
+    RESULTS+=("$1: PASS")
+  else
+    RESULTS+=("$1: FAIL")
+    docker exec "$2" tail -c 2000 /var/www/html/data/nextcloud.log | tr ',' '\n' | grep -E '"message"' | tail -3
+  fi
+}
+
+docker network create "$NET" >/dev/null
+
+# adobe/s3mock: an S3-compatible test server (MinIO's Docker Hub image now needs a paid login;
+# this one is freely pullable and pre-creates a bucket via INITIAL_BUCKETS, no auth to configure).
+docker run -d --name ngb-targets-s3 --network "$NET" \
+  -e INITIAL_BUCKETS=ngbackups \
+  adobe/s3mock >/dev/null
+
+# atmoz/sftp: "user:pass:::dir" creates /home/user/dir as the upload root.
+docker run -d --name ngb-targets-sftp --network "$NET" \
+  atmoz/sftp ngbackup:ngbackuppw:::upload >/dev/null
+
+wait_tcp ngb-targets-s3 9090
+wait_tcp ngb-targets-sftp 22
+
+start_nc ngb-targets-nc-s3
+run "S3 (s3mock)" ngb-targets-nc-s3 "amazons3 -a amazons3::accesskey -o bucket=ngbackups -o hostname=ngb-targets-s3 -o port=9090 -o region=us-east-1 -o use_ssl=false -o use_path_style=true -o key=test -o secret=test"
+
+start_nc ngb-targets-nc-sftp
+run "SFTP" ngb-targets-nc-sftp "sftp -a password::password -o host=ngb-targets-sftp -o root=/upload -o user=ngbackup -o password=ngbackuppw"
+
+printf '%s\n' "${RESULTS[@]}"
+printf '%s\n' "${RESULTS[@]}" | grep -q FAIL && exit 1
+exit 0