History of gotchas/backoffice-first-access-token-lookup.md

@@ -0,0 +1,5 @@+# Avoid unconstrained first-access-token lookups++When consuming a backoffice first-access token, do not expose or use a repository method that searches only by token hash. Token validation must use `findValidByTokenHash`, which applies both expiration and single-use constraints. An unconstrained lookup can return expired or already-used tokens and create an alternate path around the validation rules.++If a future use case genuinely needs an unfiltered lookup, add it deliberately as part of that use case and document why bypassing validity checks is safe. Otherwise, keep the repository contract limited to the validity-enforcing operation and remove unused interface, adapter, and test methods together.