Add Bearer token authentication support for all API endpoints

[konard]

Summary

This PR implements Bearer token authentication via Authorization header for all master token endpoints while maintaining full backward compatibility with query parameter authentication.

Fixes link-assistant/master-plan#14

Changes

Service Layer

• Added getMasterTokenFromRequest(req) method to TokensService that:
  • Prioritizes Authorization: Bearer <token> header (recommended)
  • Falls back to ?masterToken=<token> query parameter (deprecated)
  • Logs deprecation warnings when query parameter is used
  • Throws clear error when no authentication is provided

Controllers Updated

Updated 10 endpoints across 5 controllers to use new authentication method:

1. tokensController.js (4 endpoints)

   • GET /token - Get user token
   • GET /token/has - Check if user has token
   • PUT /token - Update token balance
   • POST /token - Regenerate token

2. completionsController.js (1 endpoint)

   • POST /completions - Create completion with dialog history

3. dialogsController.js (1 endpoint)

   • GET /dialog-history - Get dialog history

4. systemMessagesController.js (2 endpoints)

   • POST /system-message - Create system message
   • GET /system-message - Get system message

5. referralController.js (2 endpoints)

   • POST /referral - Create referral
   • GET /referral - Get referral

Security Improvements

Why Bearer Token in Headers is More Secure

Based on OAuth 2.0 RFC 6750 and 2025 security best practices:

Query Parameter Risks:

• ❌ Exposed in web server access logs
• ❌ Stored in browser history
• ❌ Logged by proxies and load balancers
• ❌ Leaked via Referer headers
• ❌ Visible in URL sharing/screenshots

Header Benefits:

• ✅ Not logged by default in most servers
• ✅ Not stored in browser history
• ✅ Not leaked via Referer headers
• ✅ Industry standard (OAuth 2.0, OpenAI, etc.)
• ✅ Better separation of concerns

OAuth 2.0 RFC 6750 Quote:

"The HTTP request URI query parameters SHOULD NOT be used to transport access tokens."

Backward Compatibility

✅ No breaking changes - all existing code continues to work

Query Parameter Support (Deprecated)

# Still works, but logs deprecation warning
curl "https://api.example.com/token?userId=123&masterToken=secret"

New Header Support (Recommended)

# Recommended approach
curl -H "Authorization: Bearer secret" \
  "https://api.example.com/token?userId=123"

Testing

Manual Testing Checklist

• Test Bearer header authentication on all 10 endpoints
• Test query parameter authentication still works (backward compatibility)
• Verify deprecation warnings appear in logs
• Test invalid token returns 401 with clear error message
• Test missing token returns 401 with helpful error message

Example Test Commands

Test Bearer header (recommended):

export MASTER_TOKEN="your-master-token"
curl -X GET "http://localhost:3000/token?userId=123" \
  -H "Authorization: Bearer ${MASTER_TOKEN}"

Test query parameter (deprecated, should log warning):

curl -X GET "http://localhost:3000/token?userId=123&masterToken=${MASTER_TOKEN}"

Test missing authentication:

curl -X GET "http://localhost:3000/token?userId=123"
# Expected: 401 with message about missing Authorization header

Migration Guide for API Consumers

For Telegram Bot

Before:

const response = await fetch(
  `${API_URL}/token?userId=${userId}&masterToken=${MASTER_TOKEN}`
);

After:

const response = await fetch(
  `${API_URL}/token?userId=${userId}`,
  {
    headers: {
      'Authorization': `Bearer ${MASTER_TOKEN}`
    }
  }
);

Timeline

Phase	Action
Phase 1 (Immediate)	Deploy this PR - both methods work
Phase 2 (Next 3 months)	Update API consumers to use headers
Phase 3 (Months 6-12)	Monitor deprecation warnings
Phase 4 (v2.0.0)	Remove query parameter support (breaking change)

Benefits

1. Enhanced Security: Follows OAuth 2.0 RFC 6750 and industry best practices
2. OpenAI Compatibility: Better alignment with OpenAI API standard (important for Cursor support)
3. Backward Compatible: No breaking changes during transition period
4. Clear Migration Path: Deprecation warnings guide users to new approach
5. Future-proof: Easier to add OAuth 2.0 flows later

Related Issues & PRs

• Fixes Allow to use bearer header in all our API link-assistant/master-plan#14
• Related: Support Cursor by our API Gateway for OpenAI models link-assistant/master-plan#8 (Cursor Support via API Gateway)
• Master plan PR: Allow to use bearer header in all our API link-assistant/master-plan#39

Additional Documentation

See detailed documentation in master-plan repository:

• BEARER_TOKEN_SOLUTION.md
• IMPLEMENTATION_PLAN.md

---

🤖 Generated with Claude Code