From d60f97413fe5a0b4a81d49b6a53d6c4739a14679 Mon Sep 17 00:00:00 2001 From: boban Date: Fri, 19 Jun 2026 22:16:37 +0200 Subject: [PATCH] feat(help): security topic - 2FA access paths + extension note Co-Authored-By: Claude Opus 4.8 (1M context) --- .../help/content/de/security.blade.php | 33 +++++++++++++++++++ .../help/content/en/security.blade.php | 33 +++++++++++++++++++ tests/Feature/HelpPageTest.php | 9 +++++ 3 files changed, 75 insertions(+) create mode 100644 resources/views/livewire/help/content/de/security.blade.php create mode 100644 resources/views/livewire/help/content/en/security.blade.php diff --git a/resources/views/livewire/help/content/de/security.blade.php b/resources/views/livewire/help/content/de/security.blade.php new file mode 100644 index 0000000..47c4121 --- /dev/null +++ b/resources/views/livewire/help/content/de/security.blade.php @@ -0,0 +1,33 @@ +@php + $h = 'font-display text-base font-semibold text-ink'; + $p = 'text-sm leading-relaxed text-ink-2'; + $li = 'text-sm leading-relaxed text-ink-2'; + $code = 'rounded bg-inset px-1.5 py-0.5 font-mono text-[12px] text-accent-text'; +@endphp + +
+

Zwei-Faktor-Authentifizierung

+

2FA ist optional, aber empfohlen. Du kannst unter Einstellungen → Sicherheit einrichten:

+
    +
  • TOTP (Authenticator-App, z. B. „Google Authenticator") — ein zeitbasierter 6-stelliger Code.
    • +
  • Security-Key (Hardware, z. B. YubiKey) — einstecken und einmal tippen.
    • +
  • Backup-Codes — einmalige Codes als Notfall-Zugang.
    • +
+
+ +
+

Wichtig: Zugangswege & welcher Faktor wo funktioniert

+

Ein Security-Key (YubiKey) funktioniert nur über die HTTPS-Domain — WebAuthn braucht einen sicheren Kontext und die Domain als Kennung (rpId). Über die Domain wird die Security-Key-Anmeldung angeboten und funktioniert.

+

Über den Bare-IP-/HTTP-Recovery-Weg (http://<Server-IP>) lässt sich nicht per Security-Key anmelden. Dort musst du einen Backup-Code verwenden.

+

TOTP funktioniert überall — auch über Bare-IP/HTTP. Wer TOTP nutzt, braucht für den Bare-IP-Weg keinen Backup-Code.

+
    +
  • Nutzt du nur einen Security-Key: bewahre die Backup-Codes auf — sie sind dein einziger Weg über den Bare-IP-Recovery-Pfad.
    • +
  • Nutzt du (auch) TOTP: du bist auf allen Wegen abgedeckt, ohne Backup-Codes nötig zu haben.
    • +
+
+ +
+

Passwort-Manager-Erweiterungen (Bitwarden, Kaspersky …)

+

Browser-Erweiterungen können die Security-Key-Registrierung abfangen und stattdessen „Passkey speichern" anbieten. Clusev fordert korrekt einen Hardware-Schlüssel an (cross-platform, nicht-auffindbar, mit dem Hinweis security-key), aber eine Webseite kann Erweiterungen nicht abschalten.

+

Lösung: in der Erweiterung die Passkey-Übernahme für diese Seite deaktivieren (z. B. Bitwarden → „Nach Passkeys fragen" aus), oder den Schlüssel in einem Browser/Fenster ohne diese Erweiterung registrieren (z. B. ein privates Fenster). Der Login mit dem Schlüssel funktioniert danach auch mit aktiver Erweiterung.

+
diff --git a/resources/views/livewire/help/content/en/security.blade.php b/resources/views/livewire/help/content/en/security.blade.php new file mode 100644 index 0000000..fba0eab --- /dev/null +++ b/resources/views/livewire/help/content/en/security.blade.php @@ -0,0 +1,33 @@ +@php + $h = 'font-display text-base font-semibold text-ink'; + $p = 'text-sm leading-relaxed text-ink-2'; + $li = 'text-sm leading-relaxed text-ink-2'; + $code = 'rounded bg-inset px-1.5 py-0.5 font-mono text-[12px] text-accent-text'; +@endphp + +
+

Two-factor authentication

+

2FA is optional but recommended. Under Settings → Security you can set up:

+
    +
  • TOTP (authenticator app, e.g. "Google Authenticator") — a time-based 6-digit code.
    • +
  • Security key (hardware, e.g. YubiKey) — plug in and tap once.
    • +
  • Backup codes (Backup-Code) — one-time codes for emergency access.
    • +
+
+ +
+

Important: access paths & which factor works where

+

A security key (YubiKey) only works over the HTTPS domain — WebAuthn needs a secure context and the domain as its identifier (rpId). Over the domain, security-key sign-in is offered and works.

+

Over the bare-IP / HTTP recovery path (http://<server-ip>) you cannot sign in with a security key. There you must use a backup code (Backup-Code).

+

TOTP works everywhere — including bare-IP/HTTP. If you use TOTP you do not need a backup code for the bare-IP path.

+
    +
  • If you use only a security key: keep your backup codes — they are your only way in over the bare-IP recovery path.
    • +
  • If you (also) use TOTP: you are covered on every path without needing backup codes.
    • +
+
+ +
+

Password-manager extensions (Bitwarden, Kaspersky …)

+

Browser extensions can intercept security-key registration and offer to "save a passkey" instead. Clusev correctly requests a hardware key (cross-platform, non-resident, with the security-key hint), but a website cannot disable extensions.

+

Fix: turn off the extension's passkey handling for this site (e.g. Bitwarden → "Ask to save and use passkeys" off), or register the key in a browser/window without that extension (e.g. a private window). Signing in with the key works afterwards even with the extension active.

+
diff --git a/tests/Feature/HelpPageTest.php b/tests/Feature/HelpPageTest.php index d2edd92..9c06098 100644 --- a/tests/Feature/HelpPageTest.php +++ b/tests/Feature/HelpPageTest.php @@ -46,4 +46,13 @@ class HelpPageTest extends TestCase ->assertSee('TRUSTED_PROXY_CIDR') ->assertDontSee('Zoraxy'); // generic — no product names } + + public function test_security_topic_explains_the_2fa_access_paths(): void + { + $this->actAsAdmin(); + Livewire::test(Index::class) + ->set('topic', 'security') + ->assertSee('Backup-Code') + ->assertSee('TOTP'); + } }