P1: fix(auth): offer recovery after OTP lockout

[aspiers]

Summary

Give users a clear way forward after better-auth rejects further attempts for an OTP. Interactive sign-in can send a new code, while account settings and recovery show honest guidance instead of implying that the locked code can still work.

Changes

• Classify only the specific too-many-attempts response as lockout
• Offer an inline resend action while the authorization flow is still live
• Share lockout-aware error guidance across account login and recovery
• Add focused unit and Cucumber coverage

Testing

• pnpm format:check
• pnpm lint
• pnpm typecheck
• pnpm test
• pnpm test:coverage
• Cucumber dry run with the required test URLs

Screenshots

Before: lockout produced a dead-end error with no direct recovery action.

After: the lockout state offers an inline Send a new code action. The preview response was controlled to isolate the final rendered state, including the sentence punctuation before the action.

Notes

• The first PR-attached E2E attempt was blocked by Railway’s resolved build/deployment incident. After the deployment completed, the current SHA passed the full deployed suite in run 30563779378.

• Focused extraction and review of work originally proposed in [WIP] many usability fixes (needs untangling) #165.

• The classifier is necessarily coupled to better-auth's English error message because these call sites receive no structured lockout code.

• PR auth: support mobile paste in segmented code input #204 overlaps only the interactive OTP-control portion; the account-settings and recovery changes are independent.

• The initial deployed E2E run exposed an undefined step phrase; commit 16b752a corrected it and the deployed suite then passed.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
epds-demo	Ready	Preview	Aug 4, 2026 10:16pm

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 664a90dc-ebb3-4e9a-a27f-e995d7416d1f

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[changeset-bot]

🦋 Changeset detected

Latest commit: 2e00832

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[railway-app]

🚅 Deployed to the ePDS-pr-217 environment in ePDS

Service	Status	Web	Updated (UTC)
@certified-app/demo	✅ Success (View Logs)	Web	Aug 4, 2026 at 10:16 pm
@certified-app/demo untrusted	✅ Success (View Logs)	Web	Aug 4, 2026 at 10:16 pm
@certified-app/auth-service	✅ Success (View Logs)	Web	Aug 4, 2026 at 10:15 pm
@certified-app/pds-core	✅ Success (View Logs)	Web	Aug 4, 2026 at 10:15 pm

[coveralls-official]

Coverage Report for CI Build 30955683423

Coverage increased (+0.2%) to 58.124%

Details

• Coverage increased (+0.2%) from the base build.
• Patch coverage: 1 uncovered change across 1 file (6 of 7 lines covered, 85.71%).
• 1 coverage regression across 1 file.

Uncovered Changes

File	Changed	Covered	%
packages/auth-service/src/routes/recovery.ts	1	0	0.0%
Total (2 files)	7	6	85.71%

Coverage Regressions

1 previously-covered line in 1 file lost coverage.

File	Lines Losing Coverage	Coverage
packages/auth-service/src/routes/account-login.ts	1	0.0%

---

Coverage Stats

Relevant Lines:	3111
Covered Lines:	1795
Line Coverage:	57.7%
Relevant Branches:	1942
Covered Branches:	1142
Branch Coverage:	58.81%
Branches in Coverage %:	Yes
Coverage Strength:	9.78 hits per line

---

💛 - Coveralls

[aspiers]

There needs to be a . in between "Too many attempts" and "Send new code".

[aspiers]

(reply generated by OpenAI Codex)

Addressed the punctuation feedback in 66a7cf9. Inline actions now add a period when the error text lacks terminal punctuation, and the browser step asserts the rendered .<space>Send a new code contract.

[aspiers]

(reply generated by OpenAI Codex)

Follow-up on the punctuation feedback: the PR description’s after screenshot has also been refreshed from the corrected renderer and now visibly shows “Too many attempts. Send a new code”.

[aspiers]

(reply generated by OpenAI Codex)

CI context: the latest PR-attached E2E job did not execute the suite; it timed out waiting for Railway to mark deployment 66a7cf9 successful. Railway has an active build/deployment delay incident. The explicit environment run reached the suite but confirmed the preview still serves the prior revision, so I am not treating that run as validation of this final amendment.

[aspiers]

(reply generated by OpenAI Codex)

Railway’s incident is resolved, the final deployment completed, and the current SHA now passes the full deployed E2E suite: https://github.com/hypercerts-org/ePDS/actions/runs/30563779378

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud