Implement SEP-10 authentication middleware

[Armolas]

Description

Implements Stellar-based authentication middleware using signed transactions (SEP-10 pattern) to verify wallet ownership and secure API endpoints. The middleware extracts Bearer tokens from request headers, verifies Stellar signatures using stellar-sdk, and attaches authenticated user information to requests.

Type of Change

• 🐛 Bug fix (non-breaking change which fixes an issue)
• ✨ New feature (non-breaking change which adds functionality)
• 💥 Breaking change (fix or feature that would cause existing functionality to not work as expected)
• 📚 Documentation update
• 🔧 Refactoring (no functional changes)
• ⚡ Performance improvement
• 🧪 Test addition or update

Related Issues

Closes #74

Changes Made

New Files

• src/middleware/auth.middleware.ts - Core authentication middleware with signature verification logic
  • authMiddleware - Requires valid authentication (returns 401 if missing/invalid)
  • optionalAuthMiddleware - Allows requests with or without authentication
• src/types/auth.types.ts - TypeScript type definitions for authentication
  • AuthUser interface - Authenticated user shape
  • AuthenticatedRequest interface - Express request with user attached
• docs/AUTHENTICATION.md - Comprehensive authentication documentation with examples

Modified Files

• src/routes/v1/user.routes.ts - Added protected GET /v1/users/me endpoint as example
• src/controllers/user.controller.ts - Added getCurrentUser controller
  • Returns user from database if exists
  • Returns in-memory user object if database record missing (database independence)
• src/config/swagger.ts - Added BearerAuth security scheme to OpenAPI spec
• package.json - Added @stellar/stellar-sdk dependency for signature verification

Key Implementation Details

✅ Extract token from Bearer header - Validates Authorization: Bearer <xdr> format
✅ Verify signature against public key - Uses stellar-sdk to cryptographically verify transaction signatures
✅ Attach req.user object - Adds { publicKey, id? } to request for downstream use
✅ Database independence - Creates in-memory user if DB lookup fails (never blocks on missing DB record)

Additional Features

• Network support (testnet/mainnet) via STELLAR_NETWORK environment variable
• Transaction time bounds validation to prevent replay attacks
• Comprehensive error messages for debugging authentication issues
• Logger integration for security audit trail

Testing

Test Coverage

• Unit tests added/updated
• Integration tests added/updated
• Manual testing performed

Test Steps

Manual Testing Performed:

1. Valid Authentication

   • Created Stellar signed transaction with test keypair
   • Encoded transaction to XDR format
   • Sent request to GET /v1/users/me with Authorization: Bearer <xdr>
   • Verified 200 response with user data

2. Missing Token

   • Sent request without Authorization header
   • Verified 401 response with appropriate error message

3. Invalid Signature

   • Modified XDR signature to be invalid
   • Verified 401 response indicating invalid signature

4. Database Independence

   • Authenticated with valid signature for non-existent user
   • Verified 200 response with in-memory user object

5. Network Configuration

   • Tested with STELLAR_NETWORK=testnet
   • Verified testnet network passphrase used for validation

To Test This PR:

1. Start the backend server: npm run dev
2. Create a Stellar signed transaction (see AUTHENTICATION.md for example)
3. Send authenticated request:

   curl -X GET http://localhost:3001/v1/users/me \
     -H "Authorization: Bearer <your_signed_transaction_xdr>"

4. Verify successful authentication and user data response

Breaking Changes

None - This is a new feature that adds authentication capabilities without modifying existing endpoints.

Screenshots/Demo

N/A - Backend API feature

Checklist

• My code follows the project's style guidelines
• 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
• I have checked for breaking changes and documented them if applicable

Additional Notes

Security Considerations

• All signature verification is done server-side using cryptographic validation
• No sensitive credentials stored on server
• Time-bound transactions prevent replay attacks when implemented by clients
• Logger captures authentication attempts for security auditing

Documentation

Complete usage guide available in docs/AUTHENTICATION.md including:

• Detailed implementation guide
• Client-side transaction signing examples
• Error response documentation
• TypeScript type references
• SEP-10 specification links

Future Work

• Add unit tests for middleware functions
• Add integration tests for protected endpoints
• Consider implementing SEP-10 challenge/response flow for enhanced security
• Add rate limiting specific to authentication endpoints

[ogazboiz]

hey! thanks for the solid implementation of the SEP-10 auth middleware. the documentation looks great and the logic seems sound for a first pass.

however, the CI checks are currently failing on several fronts (Backend, Frontend, and Dependency Scan). could you take a look at the logs in the "Checks" tab and see what's causing the break?

also, it looks like there might be some unrelated changes or conflicts in the package-lock.json. it would be great if you could clean that up while you're at it!

let us know once CI is green and we'll do a final review.

[ogazboiz]

hey, thanks for the contribution!

just had a look at this — the backend and frontend CI checks are currently failing and there are merge conflicts with main.

could you pull the latest changes, resolve the conflicts, and take a look at the workflow logs under the "Checks" tab to fix the failing steps?

once that's sorted let us know and we'll take another look — happy to help if you get stuck! if you want to contribute more or follow up if issues are open, join us on Telegram: https://t.me/+DOylgFv1jyJlNzM0