ADR-011: Magic Link Recovery Deferred to v0.2 

Context 

The design includes three recovery mechanisms: password fallback, recovery codes, and magic link (email-based one-time login). All three are in scope for the extension, but implementing all in v0.1 would increase the MVP scope significantly.

Magic link specifically requires:

• Email sending infrastructure (TYPO3 mail configuration)
• Token generation and secure storage
• Email template (FluidEmail or custom)
• Verification endpoint
• User enumeration prevention on the request endpoint
• Testing of email delivery in CI

Decision 

Defer magic link to v0.2. Ship v0.1 with password fallback + recovery codes.

v0.1 scope:

• Password fallback (free, felogin already handles it)
• Recovery codes (self-contained, no external dependencies)

v0.2 scope:

• MagicLinkService implementation
• RecoveryController magic link endpoints
• FluidEmail template for magic link email
• MagicLinkRequestedEvent for custom email rendering
• Site configuration for enabling/disabling magic link

The service interface and event class will be defined in v0.1 (as part of the architecture), but the implementation will be stubbed / throw NotImplementedException.

Consequences 

Positive:

• Smaller v0.1 scope, faster to ship
• Password + recovery codes already cover the critical recovery paths
• v0.2 can focus on polish: magic link + admin dashboard + adoption charts

Negative:

• Sites that disable password login AND lose recovery codes have no v0.1 fallback
• Users expecting magic link from day one will be disappointed

Mitigation:

• Enforced enforcement level (which blocks passwords) should not be used until v0.2 ships magic link. Documentation will warn about this.
• Recovery codes are prominently presented at enrollment to ensure users save them
• Admin unlock capability (via admin module) as emergency escape hatch

Alternatives Considered 

Ship all three in v0.1: Would delay the MVP by 1-2 weeks for email template design, mail testing infrastructure, and user enumeration prevention on the request endpoint. The benefit is marginal since password + recovery codes are sufficient for the initial rollout.