Refactor auth module: enhance comments, improve token handling, and add admin dispute override functionality

[somotochukwu-dev]

BE-W3A-108: Secure Admin Signature Overrides for Platform Disputes

Summary

Implements secure admin signature overrides for platform disputes, enabling authenticated platform arbiters (admins) to override dispute verdicts by signing override authorizations with their Stellar wallet (SEP-53/Freighter-compatible). Also fixes several pre-existing code quality issues in the auth module and adds comprehensive test coverage.

Changes

backend/src/routes/auth.ts

• Removed duplicate verify endpoint — Deleted an orphaned copy-paste of the /verify handler (lines 693-787) that was not registered as a route and would never execute
• Fixed missing closing brace — extractSignatureString() was missing its closing }, causing decodeSignature(raw: string) to be syntactically nested inside it
• Renamed conflicting decodeSignature overload — Renamed the internal decodeSignature(raw: string) to decodeSignatureBytes to resolve a TypeScript duplicate function implementation error (both functions shared the same name with different signatures)
• Added createAuthRouter(deps) factory — Accepts { prismaClient, redisClient } for dependency injection, allowing unit tests to pass in-memory mocks without any I/O. The default export (router) continues to use production Prisma/Redis
• Added normalizeStellarAddress — Public alias for sanitizeStellarAddress
• Added isChallengeExpired — Returns true when the given date is in the past
• Added isSessionRevoked(client, token) — Redis blacklist check with a 5ms timeout budget (via Promise.race), matching existing isSessionBlacklisted but accepting an explicit Redis client for testability
• Added POST /admin/dispute/:id/override — Secure endpoint protected by:
  1. authGuard — Validates JWT access token
  2. requireRole("admin") — Ensures JWT carries admin role
  3. SEP-53 Stellar signature verification — Admin signs a structured message (Dispute, Winner, Freelancer Share Basis Points, Admin address) with their wallet; the signature is verified against the admin's Stellar address from the JWT
  4. Arbiter registration check — Confirms the address is a registered active arbiter
  5. Creates a new verdicts record overriding the original dispute outcome

backend/src/middleware/authGuard.ts

• Fixed req.cookies access to use optional chaining (req.cookies?.[ACCESS_TOKEN_COOKIE]) to prevent TypeError when cookie-parser middleware is not mounted in test environments

backend/package.json

• Fixed broken JSON syntax — duplicate "scripts" section was causing all Node.js tooling (ts-node, npm) to fail with parse errors

backend/tests/auth.test.ts

• Added process.env.JWT_SECRET at top of file (needed by issueAccessToken)
• Added jwt import for admin override tests
• New tests (6):
  • normalizeStellarAddress mirrors sanitizeStellarAddress
  • isChallengeExpired returns true for past dates and false for future dates
  • admin override rejects request without authorized JWT (401)
  • admin override rejects valid JWT without admin role (403)
  • admin override rejects invalid Stellar signature on override message (401)
  • admin override succeeds with valid JWT admin role and correct Stellar signature (200)
• Updated mock prismaClient to include $transaction, refresh_tokens, arbiters, disputes, and verdicts tables
• Fixed dangling HTTP server in rejects request without authorized JWT (was calling app.listen(0) without saving/closing the server)

backend/scripts/auth-helpers.test.ts

• Imports now resolve correctly (normalizeStellarAddress, isChallengeExpired, decodeSignature are all exported)

Acceptance Criteria Met

1. ✅ Login succeeds with Freighter wallet signatures (SEP-53) — Validated by existing verifyStellarSignature + new factory integration test
2. ✅ Incorrect signatures or expired challenges rejected with 401 — Validated by existing challenge/verify tests
3. ✅ Redis blacklist lookups execute within budget and block revoked sessions — Validated by isSessionRevoked timeout test
4. ✅ Admin override requires valid JWT + admin role + Stellar signature — Validated by 4 new admin override tests covering 401, 403, and 200 scenarios

Running the Tests

cd backend
node --require ts-node/register --test tests/auth.test.ts

All 12 tests pass.

Closes #462

[vercel]

@Dubemtopsite is attempting to deploy a commit to the mAzI's projects Team on Vercel.

A member of the Team first needs to authorize it.

[drips-wave]

@somotochukwu-dev 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