diff --git a/README.md b/README.md
index 01997c5..f2d8b4d 100644
--- a/README.md
+++ b/README.md
@@ -70,16 +70,20 @@ The templates are Vue files with Tailwind classes. Maizzle inlines the CSS and w
{{ $subject }}
```
-A notification then returns those views from `toMail()`:
+Keyring sends the security notices itself, so the app only gives them their look. One callback in `KeyringServiceProvider` builds every notice from the one template:
```php
-return (new MailMessage)->subject($this->subject())->view(
- ['html' => 'emails.keyring.notice', 'text' => 'emails.keyring.text.notice'],
- ['subject' => $this->subject(), 'intro' => $this->intro(), /* ... */],
-);
+SecurityNotice::toMailUsing(fn (SecurityNotice $notice, object $notifiable) => (new MailMessage)
+ ->subject($notice->subject())
+ ->view(
+ ['html' => 'emails.keyring.notice', 'text' => 'emails.keyring.text.notice'],
+ ['subject' => $notice->subject(), 'intro' => $notice->intro(), /* ... */],
+ ));
```
-Blade escapes what the HTML views print, so a name someone typed for their security key can't add a link to a genuine security email. The twelve security notices share one template through `SecurityNotice::toMail()`; each notice class only says its subject and intro.
+The five emails a flow needs (the emailed code, the two for an email change, and the two that answer an address that's already taken) each have their own template, so they're the app's own classes in `app/Notifications/Keyring`, registered with `Keyring::notifications()`.
+
+Blade escapes what the HTML views print, so a name someone typed for their security key can't add a link to a genuine security email.
## Demo accounts
diff --git a/app/Notifications/Keyring/AccountLocked.php b/app/Notifications/Keyring/AccountLocked.php
deleted file mode 100644
index 639a8ac..0000000
--- a/app/Notifications/Keyring/AccountLocked.php
+++ /dev/null
@@ -1,23 +0,0 @@
- $this->name]);
- }
-}
diff --git a/app/Notifications/Keyring/AuthenticatorRemoved.php b/app/Notifications/Keyring/AuthenticatorRemoved.php
deleted file mode 100644
index fc63441..0000000
--- a/app/Notifications/Keyring/AuthenticatorRemoved.php
+++ /dev/null
@@ -1,18 +0,0 @@
- $this->name]);
- }
-}
diff --git a/app/Notifications/Keyring/CloneSuspected.php b/app/Notifications/Keyring/CloneSuspected.php
deleted file mode 100644
index 64801eb..0000000
--- a/app/Notifications/Keyring/CloneSuspected.php
+++ /dev/null
@@ -1,18 +0,0 @@
- $this->name]);
- }
-}
diff --git a/app/Notifications/Keyring/EmailChangeNotice.php b/app/Notifications/Keyring/EmailChangeNotice.php
index ea9a2bd..f8e741e 100644
--- a/app/Notifications/Keyring/EmailChangeNotice.php
+++ b/app/Notifications/Keyring/EmailChangeNotice.php
@@ -4,6 +4,7 @@
namespace App\Notifications\Keyring;
+use App\Support\SupportContact;
use Illuminate\Notifications\Messages\MailMessage;
use Illuminate\Notifications\Notification;
@@ -15,8 +16,6 @@
*/
class EmailChangeNotice extends Notification
{
- use ShowsSupportContact;
-
/**
* @param string $email the new address, with most of its name hidden
* @param string|null $contact "support_contact" from config/keyring.php: a URL or an address
@@ -42,7 +41,7 @@ public function toMail(object $notifiable): MailMessage
'email' => $this->email,
'revertUrl' => $this->revertUrl,
'confirmUrl' => $this->confirmUrl,
- ...$this->supportContact(),
+ ...SupportContact::for($this->contact),
]);
}
}
diff --git a/app/Notifications/Keyring/EmailChangeReverted.php b/app/Notifications/Keyring/EmailChangeReverted.php
deleted file mode 100644
index 6342069..0000000
--- a/app/Notifications/Keyring/EmailChangeReverted.php
+++ /dev/null
@@ -1,18 +0,0 @@
- $this->remaining]);
- }
-}
diff --git a/app/Notifications/Keyring/RecoveryCodesGenerated.php b/app/Notifications/Keyring/RecoveryCodesGenerated.php
deleted file mode 100644
index 7457ce1..0000000
--- a/app/Notifications/Keyring/RecoveryCodesGenerated.php
+++ /dev/null
@@ -1,18 +0,0 @@
-
- */
- public function via(object $notifiable): array
- {
- return ['mail'];
- }
-
- /**
- * Every notice uses one Maizzle template, resources/emails/keyring/notice.vue,
- * which `npm run emails` builds into these two views. Blade escapes what
- * the HTML one prints, so a name someone typed can't add markup to it.
- */
- public function toMail(object $notifiable): MailMessage
- {
- $details = array_filter([__('When') => $this->when, __('Device') => $this->device, __('IP address') => $this->ip]);
-
- return (new MailMessage)->subject($this->subject())->view(['html' => 'emails.keyring.notice', 'text' => 'emails.keyring.text.notice'], [
- 'subject' => $this->subject(),
- 'intro' => $this->intro(),
- 'details' => array_map(fn (string $label, string $value) => ['label' => $label, 'value' => $value], array_keys($details), $details),
- 'actionText' => $this->action(),
- 'actionUrl' => $this->action() === null ? null : $this->url,
- ...$this->supportContact(),
- ]);
- }
-}
diff --git a/app/Notifications/Keyring/ShowsSupportContact.php b/app/Notifications/Keyring/ShowsSupportContact.php
deleted file mode 100644
index caa7e59..0000000
--- a/app/Notifications/Keyring/ShowsSupportContact.php
+++ /dev/null
@@ -1,34 +0,0 @@
- $this->contact,
- 'contactUrl' => match (true) {
- $this->contact === null => null,
- filter_var($this->contact, FILTER_VALIDATE_EMAIL) !== false => 'mailto:'.$this->contact,
- Str::startsWith($this->contact, ['https://', 'http://']) => $this->contact,
- default => null,
- },
- ];
- }
-}
diff --git a/app/Notifications/Keyring/SuspiciousActivity.php b/app/Notifications/Keyring/SuspiciousActivity.php
deleted file mode 100644
index 8a3f06c..0000000
--- a/app/Notifications/Keyring/SuspiciousActivity.php
+++ /dev/null
@@ -1,18 +0,0 @@
- $this->reasons]);
- }
-}
diff --git a/app/Notifications/Keyring/VerificationCode.php b/app/Notifications/Keyring/VerificationCode.php
index 1e12c21..66af1a0 100644
--- a/app/Notifications/Keyring/VerificationCode.php
+++ b/app/Notifications/Keyring/VerificationCode.php
@@ -4,6 +4,7 @@
namespace App\Notifications\Keyring;
+use App\Support\SupportContact;
use Illuminate\Notifications\Messages\MailMessage;
use Illuminate\Notifications\Notification;
@@ -13,8 +14,6 @@
*/
class VerificationCode extends Notification
{
- use ShowsSupportContact;
-
public function __construct(
#[\SensitiveParameter] public string $code,
public int $minutes,
@@ -36,7 +35,7 @@ public function toMail(object $notifiable): MailMessage
'code' => trim(chunk_split($this->code, 4, ' ')),
'minutes' => $this->minutes,
'enrolling' => $this->enrolling,
- ...$this->supportContact(),
+ ...SupportContact::for($this->contact),
]);
}
}
diff --git a/app/Providers/KeyringServiceProvider.php b/app/Providers/KeyringServiceProvider.php
index 2287df1..df83090 100644
--- a/app/Providers/KeyringServiceProvider.php
+++ b/app/Providers/KeyringServiceProvider.php
@@ -9,8 +9,10 @@
use App\Actions\Keyring\UpdateUserPassword;
use App\Actions\Keyring\ValidateEmailChange;
use App\Notifications\Keyring as Notifications;
+use App\Support\SupportContact;
use Illuminate\Contracts\Foundation\Application;
use Illuminate\Contracts\Http\Kernel;
+use Illuminate\Notifications\Messages\MailMessage;
use Illuminate\Support\ServiceProvider;
use Keyring\Facades\Keyring;
use Keyring\Factors\EmailCode;
@@ -19,9 +21,8 @@
use Keyring\Factors\Totp;
use Keyring\Factors\WebAuthn;
use Keyring\Login\Requirement;
-use Keyring\Risk\Action;
-use Keyring\Risk\Level;
-use Keyring\Risk\Risk;
+use Keyring\Notifications\CloneSuspected;
+use Keyring\Notifications\SecurityNotice;
use Keyring\Risk\Signals\InactiveAccount;
use Keyring\Risk\Signals\NewDevice;
use Keyring\Risk\Signals\RepeatedFactorFailures;
@@ -63,55 +64,61 @@ public function boot(): void
Keyring::updateUserPasswordsUsing(UpdateUserPassword::class);
Keyring::validateEmailChangesUsing(ValidateEmailChange::class);
- // Every email Keyring sends is one of this app's notifications, in
- // app/Notifications/Keyring, built from the Maizzle templates in
- // resources/emails. A security notice left out here isn't sent.
+ // Keyring sends its own security notices. This app only gives them
+ // its look: every one is built from one Maizzle template,
+ // resources/emails/keyring/notice.vue.
+ SecurityNotice::toMailUsing(self::noticeMail(...));
+
+ // The five emails a flow needs each have a shape of their own, so
+ // they're this app's classes, in app/Notifications/Keyring, with a
+ // template each. The suspected clone is the one notice Keyring
+ // leaves off until it's asked for. The demo sends it.
Keyring::notifications([
'verification_code' => Notifications\VerificationCode::class,
'confirm_email_change' => Notifications\ConfirmEmailChange::class,
'email_change_notice' => Notifications\EmailChangeNotice::class,
'email_address_in_use' => Notifications\EmailAddressInUse::class,
'already_registered' => Notifications\AlreadyRegistered::class,
- 'password_changed' => Notifications\PasswordChanged::class,
- 'authenticator_added' => Notifications\AuthenticatorAdded::class,
- 'authenticator_removed' => Notifications\AuthenticatorRemoved::class,
- 'recovery_code_used' => Notifications\RecoveryCodeUsed::class,
- 'recovery_codes_generated' => Notifications\RecoveryCodesGenerated::class,
- 'email_changed' => Notifications\EmailChanged::class,
- 'account_locked' => Notifications\AccountLocked::class,
- 'new_device' => Notifications\NewDevice::class,
- 'second_factor_failed' => Notifications\SecondFactorFailed::class,
- 'suspicious_activity' => Notifications\SuspiciousActivity::class,
- 'email_change_reverted' => Notifications\EmailChangeReverted::class,
- // An install leaves this one commented out. The demo sends it.
- 'clone_suspected' => Notifications\CloneSuspected::class,
+ 'clone_suspected' => CloneSuspected::class,
]);
- // What makes a sign in or a session look wrong, and what to do about
- // it. A sign in after a long quiet period, or after several failed
- // attempts, emails the owner as well as asking for a second factor.
- Keyring::risk()
- ->signals([
- NewDevice::class,
- RepeatedFactorFailures::class,
- SessionFingerprintChanged::class,
- InactiveAccount::class,
- SuccessAfterFailures::class,
- ])
- ->respond(fn (Risk $risk) => match ($risk->level) {
- Level::Low => Action::allow(),
- Level::Medium => $risk->has('inactive_account') || $risk->has('success_after_failures')
- ? Action::stepUp()->notify()
- : Action::stepUp(),
- Level::High => Action::stepUp()->notify(),
- Level::Critical => Action::deny()->revokeAllSessions()->notify(),
- });
+ // What makes a sign in or a session look wrong. Keyring's own
+ // response does the rest: a second factor at medium, an email to the
+ // owner from high, and a refused sign in at critical. A sign in
+ // after a long quiet period, or after several failed attempts,
+ // emails the owner whatever it scores.
+ Keyring::risk()->signals([
+ NewDevice::class,
+ RepeatedFactorFailures::class,
+ SessionFingerprintChanged::class,
+ InactiveAccount::class,
+ SuccessAfterFailures::class,
+ ]);
// Keyring's pages already match the starter kit's names (auth/login,
// auth/challenge...). Step-up confirmation reuses the challenge page.
Keyring::page('confirm', 'auth/challenge');
}
+ /**
+ * The email of every security notice, from the one Maizzle template
+ * `npm run emails` builds into these two views. Blade escapes what the
+ * HTML one prints, so a name someone typed can't add markup to it.
+ */
+ protected static function noticeMail(SecurityNotice $notice, object $notifiable): MailMessage
+ {
+ $details = array_filter([__('When') => $notice->when, __('Device') => $notice->device, __('IP address') => $notice->ip]);
+
+ return (new MailMessage)->subject($notice->subject())->view(['html' => 'emails.keyring.notice', 'text' => 'emails.keyring.text.notice'], [
+ 'subject' => $notice->subject(),
+ 'intro' => $notice->intro(),
+ 'details' => array_map(fn (string $label, string $value) => ['label' => $label, 'value' => $value], array_keys($details), $details),
+ 'actionText' => $notice->action(),
+ 'actionUrl' => $notice->action() === null ? null : $notice->url,
+ ...SupportContact::for($notice->contact),
+ ]);
+ }
+
/**
* Any security key, as the demo ships. With SECURITY_KEY_ATTESTATION set,
* only keys whose maker vouches for them, and with SECURITY_KEY_MODELS
diff --git a/app/Support/SupportContact.php b/app/Support/SupportContact.php
new file mode 100644
index 0000000..955d908
--- /dev/null
+++ b/app/Support/SupportContact.php
@@ -0,0 +1,34 @@
+ $contact,
+ 'contactUrl' => match (true) {
+ $contact === null => null,
+ filter_var($contact, FILTER_VALIDATE_EMAIL) !== false => 'mailto:'.$contact,
+ Str::startsWith($contact, ['https://', 'http://']) => $contact,
+ default => null,
+ },
+ ];
+ }
+}
diff --git a/composer.lock b/composer.lock
index 19dcd8f..d1c8898 100644
--- a/composer.lock
+++ b/composer.lock
@@ -670,7 +670,7 @@
"dist": {
"type": "path",
"url": "../keyring",
- "reference": "44a9e8ca14564751f3f4bfcf5aeaa95eb1c6007f"
+ "reference": "dcc4dc4f50027bb596f462852d88b2b674fd1af4"
},
"require": {
"bacon/bacon-qr-code": "^3.0",
diff --git a/resources/emails/keyring/notice.vue b/resources/emails/keyring/notice.vue
index 865cd2c..09c8cc5 100644
--- a/resources/emails/keyring/notice.vue
+++ b/resources/emails/keyring/notice.vue
@@ -1,6 +1,6 @@
diff --git a/tests/Feature/Emails/KeyringEmailsTest.php b/tests/Feature/Emails/KeyringEmailsTest.php
index 4f8dc47..b90e1ba 100644
--- a/tests/Feature/Emails/KeyringEmailsTest.php
+++ b/tests/Feature/Emails/KeyringEmailsTest.php
@@ -3,16 +3,16 @@
namespace Tests\Feature\Emails;
use App\Models\User;
-use App\Notifications\Keyring\AccountLocked;
use App\Notifications\Keyring\AlreadyRegistered;
-use App\Notifications\Keyring\AuthenticatorAdded;
use App\Notifications\Keyring\EmailChangeNotice;
-use App\Notifications\Keyring\NewDevice;
use App\Notifications\Keyring\VerificationCode;
use Illuminate\Notifications\Messages\MailMessage;
use Illuminate\Support\Facades\File;
use Keyring\Facades\Keyring;
use Keyring\KeyringManager;
+use Keyring\Notifications\AccountLocked;
+use Keyring\Notifications\AuthenticatorAdded;
+use Keyring\Notifications\NewDevice;
use PHPUnit\Framework\Attributes\DataProvider;
use Tests\TestCase;