Defines one-time email-link login from request through expiry, replay protection, cross-device continuation, session creation, and privacy-preserving responses under abuse and delivery failures.
Package status: reference context ready for human review. The contract and test scenarios are complete, but no claim is made that an adopting implementation has passed them.
Decision
Issue a short-lived, single-use, purpose-bound token after a neutral request response. Consume it atomically before creating a session; require an explicit continuation step and stronger verification for high-risk context changes.
Scope
- Request, delivery, link opening, confirmation, consumption, session creation, expiry, and revocation.
- Account-enumeration resistance, throttling, replay handling, and audit evidence.
- Same-device and cross-device user behavior.
Outside this block
- Password recovery, multifactor enrollment, or proof that email controls identity in every product.
- Provider-specific email deliverability architecture.
Contract
- Request responses do not reveal whether an identifier exists, while operational events distinguish delivery decisions privately.
- Tokens contain at least random entropy, purpose, account reference, issue/expiry time, and nonce; only a verifier digest is stored.
- Consumption is an atomic transition from issued to consumed and cannot create two sessions.
- Opening a link displays the target account in masked form and requires a deliberate Continue action before session creation.
- A cross-device or materially changed risk context invokes the configured step-up policy.
- Requesting another link does not make previously delivered links ambiguous: the configured latest-only or multi-valid policy is explicit.
Implementation guidance
- Rate-limit by normalized identifier hash, device/risk signal, and network range without using one dimension as the sole control.
- Bind redirect targets to an allowlist captured at issuance.
- Use server-side session creation and rotate identifiers after authentication.
- Keep raw tokens out of URLs after consumption, logs, analytics, referrers, and support tooling.
Failure handling and safeguards
- Expired, revoked, malformed, and already-used links show the same safe recovery action without disclosing account state.
- If token consumption succeeds but session delivery fails, a status lookup resolves the outcome without re-consuming the token.
- A delivery-provider retry must reuse the same message operation, not mint unlimited tokens.
Verification and operations
- Monitor request-to-delivery, delivery-to-consumption, expiry, replay, throttle, step-up, and session-creation failure rates.
- Alert on sudden identifier-hash or network clusters while preserving privacy.
- Exercise atomic consumption and log-redaction tests in every authentication release.
The executable-looking examples in this package are fixtures and acceptance contracts. Run
python tools/validate.py from the collection root to check package structure and metadata; then
implement and execute the scenarios in the target repository.
Adoption assumptions
- Names and numeric values in
example.yamlare an adoption profile, not universal defaults. - The adopting team must map actors, data classes, error vocabulary, and ownership to its system.