feat: audit and notify on WebAuthn credential registration

[devondragon]

Why

Enrolling a passkey grants a durable new way into an account, and it outlives a password change: session invalidation ends sessions, not credentials. An attacker who reaches an authenticated session can leave themselves a way back in that survives the victim's response.

Until now that produced no audit record and no notification. Spring Security owns POST /webauthn/register and nothing in this framework observed it, so a passkey could be added to an account with no trace and no signal to the owner.

Found while reviewing #365. This is independent of that feature and applies to 5.3.2 as shipped, which is why it is a separate PR.

What

• WebAuthnCredentialRegisteredEvent carrying the user, credential id, and label.
• Published from the framework's own JpaUserCredentialRepository, which every enrollment writes through regardless of which endpoint triggered it.
• WebAuthnCredentialRegistrationListener records a PasskeyRegistration audit event, then emails the owner.
• user.webauthn.notifyOnRegistration (default true) gates the email only. The audit event is unconditional, and a mail failure cannot lose it.
• New mail template and message keys that name the specific risk: a passkey survives a password change, so recovering means changing the password and removing the unrecognized passkey.

The trap this had to avoid

UserCredentialRepository.save() is also called inside authenticate(), to persist the updated signature count. Publishing on every save would have emailed the user on every passkey login.

save() already resolves the row with findById(...).orElseGet(WebAuthnCredential::new), so an absent row identifies a genuine registration with no extra query. shouldPublishNoEventWhenCredentialIsUpdated pins it; replacing the guard with if (true) fails that test.

Scope

Detective, not preventive. Preventing enrollment from a session-only actor is step-up (#335 / #365), which is off by default and does not currently gate enrollment at all. This lands regardless of what happens to that branch, and is useful on its own.

Verification

./gradlew check green, ./gradlew javadoc clean. Six new tests, written test-first.

Not verified in a browser: no end-to-end run confirming the email renders and arrives on a real enrollment. Worth a demo-app pass before release.

Compatibility

New emails will be sent on passkey registration for deployments with WebAuthn enabled, which is a visible behavior change on upgrade. Default is true deliberately: a security notification that is off by default protects nobody. Set user.webauthn.notifyOnRegistration=false to opt out.

[claude]

Review: passkey registration audit + notification

Good addition — closing a real gap (no signal at all today when a passkey is enrolled). A few things worth fixing before merge, roughly in order of importance.

1. HTML injection in the new notification email (security)

webauthn-credential-registered.html renders the passkey label unescaped:

<p th:utext="#{email.passkey-registered.intro(${label})}"></p>

label is attacker-controlled: it's whatever string is submitted in the POST /webauthn/register body, and in the exact threat model this PR targets — an attacker who has hijacked a session enrolling their own passkey — the attacker chooses it. Compare this to forgot-password-token.html, which deliberately renders user.firstName (also raw user input) via th:text (escaped), not th:utext. As written, an attacker can set label to arbitrary markup and have it injected unescaped into the very security notification meant to alert the victim.

Suggest rendering label via th:text on its own element rather than splicing it into an #{...} message and rendering the result with th:utext.

(For what it's worth, the audit log path is fine — FileAuditLogWriter.sanitizeField already strips \r, \n, and | from every field before writing, so the pipe-delimited audit record can't be forged the same way.)

2. Misplaced Javadoc in UserEmailService.java

sendPasskeyRegisteredNotification (and its own Javadoc block) got inserted between the existing Javadoc for createEmailVariables and the createEmailVariables method itself:

/**
 * Creates the email variables.
 * ...
 * @return the map
 * @throws IllegalArgumentException if appUrl is invalid (for admin-initiated resets)
 */
/**
 * Notifies the account owner that a passkey was registered on their account.
 * ...
 */
public void sendPasskeyRegisteredNotification(final User user, final String label) { ... }

private Map<String, Object> createEmailVariables(final User user, final String appUrl, final String token, final String confirmationPath) {

The first block now floats above an unrelated method and no longer documents anything; createEmailVariables is left with no Javadoc at all. Looks like a copy/paste landed in the wrong spot — worth moving the new method (with its own doc comment) down next to the other send* methods.

3. Event fires before the transaction that creates the row commits

JpaUserCredentialRepository.save() is @Transactional, and eventPublisher.publishEvent(new WebAuthnCredentialRegisteredEvent(...)) is the last statement in the method body — i.e. it runs before the surrounding transaction commits (the JPA save() call only queues the write; flush/commit happens when the @Transactional proxy returns). If that transaction then rolls back — a constraint violation, a connection drop during flush, or (if save() joins an already-open caller transaction) a later failure in that same transaction — the audit event and "a passkey was added to your account" email will already have gone out for a credential that was never actually persisted.

This project already has a pattern for exactly this class of problem: UserDeletedEvent/UserDisabledEvent are published from a TransactionSynchronization.afterCommit callback for this reason. Might be worth the same treatment here, though I'd call this low-severity in practice since nothing else appears to run after save() in the registration ceremony.

What looks right

• The registration-vs-login disambiguation (existing.isEmpty()) is correct and directly tested (shouldPublishNoEventWhenCredentialIsUpdated) — this was the trap called out in the PR description and it's solidly pinned.
• notifyOnRegistration correctly gates only the email, not the audit record, matching the stated design ("a mail failure cannot lose it").
• Both the audit publish and the email send end up dispatched asynchronously under the hood (AuditEventListener is @Async, MailService.sendTemplateMessage is @Async("dsMailExecutor") with its own retry/recover), so the synchronous WebAuthnCredentialRegistrationListener doesn't add real latency to the WebAuthn registration response despite not being @Async itself.
• Test coverage is well targeted at the specific risk (registration vs. every login, audit surviving a mail failure, notification respecting the config flag).

Nothing here should be hard to fix — #1 and #2 are small, targeted changes; #3 is optional depending on how much you want to invest in this specific corner.

[Copilot]

Pull request overview

Adds framework-level observability for WebAuthn (passkey) enrollment by publishing a dedicated registration event from the JPA credential repository, then handling it to produce an audit trail and (optionally) notify the account owner via email. This fits the framework’s security/audit posture by ensuring credential enrollment is visible even when Spring Security owns the enrollment endpoint.

Changes:

• Publish WebAuthnCredentialRegisteredEvent only when a credential row is first created (not on signature-count updates).
• Add WebAuthnCredentialRegistrationListener to emit a PasskeyRegistration audit event and optionally send a notification email (user.webauthn.notifyOnRegistration, default true).
• Add a new mail template + message keys and document the new configuration property.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/test/java/com/digitalsanctuary/spring/user/security/WebAuthnCredentialRegistrationEventTest.java	Pins “new vs updated credential” behavior to avoid notifications on login signature-count saves.
src/test/java/com/digitalsanctuary/spring/user/listener/WebAuthnCredentialRegistrationListenerTest.java	Verifies audit publication, email gating, and resilience to notification failures.
src/main/resources/templates/mail/webauthn-credential-registered.html	Adds the new passkey-registration email template.
src/main/resources/messages/dsspringusermessages.properties	Adds message keys describing passkey registration risk and user guidance.
src/main/resources/config/dsspringuserconfig.properties	Documents and defaults user.webauthn.notifyOnRegistration=true.
src/main/java/com/digitalsanctuary/spring/user/service/UserEmailService.java	Adds sendPasskeyRegisteredNotification(...) email sender for passkey enrollment.
src/main/java/com/digitalsanctuary/spring/user/security/WebAuthnRepositoryConfig.java	Publishes registration event from JpaUserCredentialRepository.save() only when the credential is new.
src/main/java/com/digitalsanctuary/spring/user/security/WebAuthnConfigProperties.java	Introduces notifyOnRegistration configuration property (default true).
src/main/java/com/digitalsanctuary/spring/user/listener/WebAuthnCredentialRegistrationListener.java	Listens for registration event, emits audit event, and conditionally sends notification email.
src/main/java/com/digitalsanctuary/spring/user/event/WebAuthnCredentialRegisteredEvent.java	Defines the event carrying user, credential id, and label.
CONFIG.md	Documents the new WebAuthn registration-notification property and its rationale.

Suppressed comments (1)

src/main/java/com/digitalsanctuary/spring/user/listener/WebAuthnCredentialRegistrationListener.java:53

• This comment says the registration flow "has already committed", but the listener runs synchronously from JpaUserCredentialRepository.save() which is @Transactional, so commit happens after this method returns. Reword to avoid implying the DB write is already committed.

            // Never let a mail failure propagate into the registration flow, which has already committed.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.