feat: add Stellar challenge auth with JWT sessions

[Josue19-08]

Description

Implements Stellar wallet challenge/verify authentication with JWT-backed sessions for the API.

Closes #2

Type of Change

• ✨ New feature
• ✅ Test addition or update
• 📝 Documentation update
• 🔧 Configuration change

Checklist

• All GitHub Actions workflows are green on this PR (required for merge)
• Commit messages follow Conventional Commits (feat:, fix:, chore:, etc.) — enforced by CI
• No secrets, API keys, .env, or credentials committed (see CONTRIBUTING.md)
• My code follows the code style of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged and published

Testing

How to Test

1. Run npm ci.
2. Set JWT_SECRET, JWT_EXPIRES_IN, AUTH_CHALLENGE_TTL_MS, STELLAR_NETWORK, and DATABASE_URL in .env.
3. Run npm run lint, npm run type-check, npm test, and npm run build.
4. Request POST /api/v1/auth/challenge, sign the returned message with the Stellar wallet private key, then submit POST /api/v1/auth/verify and call GET /api/v1/auth/me with the bearer token.

Test Coverage

• Unit tests added/updated
• Integration tests added/updated
• E2E tests added/updated (if applicable)
• Manual testing completed

Additional Notes

Changes

• Added Express app bootstrap, auth controller/routes, Joi validation, JWT auth middleware, and centralized error handling.
• Added auth_challenges persistence plus a migration for nonce expiry and single-use enforcement.
• Implemented Stellar signature verification with network-bound challenge payloads and user upsert by stellarAddress.
• Updated .env.example and Readme.md with the auth env vars and endpoint documentation.

Refresh approach

This implementation uses short-lived access JWTs only and does not persist refresh tokens. When an access token expires, the client must request a new challenge and sign it again with the Stellar wallet. That keeps server-side session state minimal and avoids introducing a separate refresh-token table in this issue. The tradeoff is more frequent wallet signatures, but the flow stays simple and keeps replay protection centered on expiring single-use nonces.

Environment variables

• JWT_SECRET
• JWT_EXPIRES_IN
• AUTH_CHALLENGE_TTL_MS
• STELLAR_NETWORK
• DATABASE_URL

For Reviewers

• Code quality and readability
• Test coverage
• Security implications
• Performance impact
• Breaking changes

[drips-wave]

@Josue19-08 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits