[Docs] backend/docs/AUTHENTICATION.md documents an outdated, replay-prone signed-XDR-as-Bearer model instead of the implemented nonce challenge/verify + JWT flow

[grantfox-oss]

Telegram (ask questions / claim the issue here first): https://t.me/+DOylgFv1jyJlNzM0

Why this matters

auth.ts requires /v1/auth/verify to submit a tx whose manageData value equals the server-issued nonce, then issues a JWT used as the Bearer token. But docs/AUTHENTICATION.md:84-104 tells clients to put their own random crypto.randomBytes(32) in manageData and send the raw signed XDR as Authorization: Bearer <signed_transaction> - the pre-nonce model that is replay-prone. It also recommends optionalAuthMiddleware (dead code) and stale error strings. A client following this doc cannot authenticate.

Acceptance criteria

• Rewrite AUTHENTICATION.md to describe the real flow: POST /v1/auth/challenge -> server nonce -> POST /v1/auth/verify with XDR containing that nonce -> JWT -> Bearer JWT
• Show building the manageData op with the server-returned nonce, not a client-random value
• Correct the error-response examples and remove the dead optionalAuthMiddleware recommendation

Files to touch

• backend/docs/AUTHENTICATION.md
• backend/src/middleware/auth.ts

Out of scope

• Changing the auth implementation itself

[charlesedeh021-cell]

@charlesedeh021-cell has applied to work on this issue as part of the Stellar Wave Program's 6th wave.

Hi maintainers!

I’d love to help out with this issue. I’ve checked the current codebase/documentation and know exactly what needs to be updated to make this clearer. I will ensure everything aligns perfectly with your existing contribution guidelines.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @charlesedeh021-cell to this issue.

[dhareymu]

@dhareymu has applied to work on this issue as part of the Stellar Wave Program's 6th wave.

Hi maintainer, deadline is almost here.

I can help you fix the issues on the project swiftly and create a PR for it in no time.

Please kindly assign it to me. I look forward to working with you. Thank you.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @dhareymu to this issue.

[iyanumajekodunmi756]

@iyanumajekodunmi756 has applied to work on this issue as part of the Stellar Wave Program's 6th wave.

I would love to work on this issue

ℹ️ Repo Maintainers: To accept this application, review their application or assign @iyanumajekodunmi756 to this issue.

[grantfox-oss]

🦊 GrantFox — @charlesedeh021-cell has been assigned to this issue!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #820)
2. Your PR will be reviewed by the LabsCrypt maintainers

Good luck! Track your progress on GrantFox.

[drips-wave]

Congratulations, @charlesedeh021-cell! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on June 30, 2026.

🧑‍💻 @charlesedeh021-cell: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊