M5: deletion delay with trash, passphrase slots, ransomware documentation

- removed snapshots go to a trash on the location and their data is only
  freed after the deletion delay, which is chosen when the key is created
  (default 7 days, 1-365) and cannot be changed afterwards; any admin can
  bring them back (occ backup:trash, backup:trash:restore, web UI)
- up to three passphrase slots open the same master key (like LUKS), so
  one person leaving or dying does not lock the company out; slot changes
  are written to every location, announced to all admins and require a
  new recovery kit confirmation, while backups keep running
- occ backup:key:slots, backup:key:slot:add|replace|remove; key init takes
  --label and --delete-delay-days
- web UI: deletion delay and first slot at key creation, slot management,
  trash per location with restore; all behind password confirmation
- README: key, slots (safe / CTO / head of IT), and protection against
  ransomware: object lock in compliance mode (e.g. 90 days), credentials
  without delete rights, provider snapshots, off-site copy

lib/Service/KeySlotService.php

@@ -0,0 +1,61 @@
+<?php
+
+declare(strict_types=1);
+
+// SPDX-FileCopyrightText: 2026 Dillard Blom
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+namespace OCA\NgBackup\Service;
+
+/**
+ * Passphrase slots (like LUKS): up to three passphrases, each opening the same master key, so
+ * that one person leaving or dying does not lock the company out of its backups. Every change
+ * 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 {
+	public function __construct(
+		private KeyService $keys,
+		private TargetService $targets,
+		private AlertService $alerts,
+	) {
+	}
+
+	public function add(#[\SensitiveParameter] string $passphrase, string $label): int {
+		$slot = $this->keys->addSlot($passphrase, $label);
+		$this->apply('slot_added', $slot);
+		return $slot;
+	}
+
+	public function replace(int $slot, #[\SensitiveParameter] string $passphrase, ?string $label = null): void {
+		$this->keys->replaceSlot($slot, $passphrase, $label);
+		$this->apply('slot_replaced', $slot);
+	}
+
+	public function remove(int $slot): void {
+		$this->keys->removeSlot($slot);
+		$this->apply('slot_removed', $slot);
+	}
+
+	private function apply(string $event, int $slot): void {
+		$wrapped = $this->keys->wrappedKey();
+		$failed = [];
+		foreach ($this->targets->list() as $t) {
+			try {
+				$this->targets->repository($t)->updateWrappedKey($wrapped);
+			} catch (\Throwable $e) {
+				$failed[] = $t->getName();
+			}
+		}
+		$label = '';
+		foreach ($this->keys->slots() as $s) {
+			if ($s['slot'] === $slot) {
+				$label = $s['label'];
+			}
+		}
+		$this->alerts->securityEvent($event, ['slot' => (string)$slot, 'label' => $label]);
+		if ($failed !== []) {
+			throw new \RuntimeException('Saved, but these locations could not be updated (they still accept the previous passphrases): ' . implode(', ', $failed));
+		}
+	}
+}