Auth Middleware (JWT Guard for Protected Routes)

[codebestia]

Background

All merchant-facing endpoints (dashboard, invoices, profile, API keys) must require a valid JWT. This middleware needs to be reusable, attach the resolved merchant to req, and return clear errors for missing, malformed, or expired tokens.

Proposed Steps

1. Create src/middleware/auth.middleware.ts
2. Extract the Bearer token from the Authorization header
3. Verify and decode the JWT using JWT_SECRET
4. Load the Merchant record from the database using sub from the token
5. Attach it to req.merchant (extend Request type in src/types/express.d.ts)
6. Call next() on success; return 401 on any failure
7. Apply the middleware to all /api/v1/merchants/*, /api/v1/invoices/*, and future protected route groups

Acceptance Criteria

• Request with valid JWT → req.merchant is populated and next() is called
• Missing Authorization header → 401 { error: "Authentication required" }
• Malformed or expired JWT → 401 { error: "Invalid or expired token" }
• Valid JWT but merchant deleted from DB → 401
• Middleware is applied at the router level (not per-route) for all protected groups
• TypeScript types are extended so req.merchant is typed as Merchant throughout the codebase

[martinshub-tech]

I'd like to take this issue. I've analyzed the root cause and am confident I can deliver a reliable fix with proper testing

[Ebenezer199914]

can i work on this

[jaynomyaro]

Hi! I’m a full-stack developer with a strong blockchain background. I’d love to handle this issue and can deliver a clean, reliable solution. Kindly assign it to me.

[Menjay7]

Hi! I came across this issue and would love to work on it. I have experience with similar tasks and I'm confident I can investigate, implement a clean solution, and thoroughly test it before submitting a PR. If the issue is still open, I would appreciate it if you could assign it to me. Thank you!

[leocagli]

I'd like to work on this issue, please assign me so I can begin implementation.

[KodeSage]

I have experience building backend systems with authentication flows, middleware, database integrations, and API security. I’ve worked with JWT-based authentication, request validation, and protecting routes by enforcing authorization rules at the application layer.

For this issue, I would first review the existing authentication setup, merchant model, and route structure to understand how JWTs and database access are currently handled. I would then create a reusable authentication middleware that extracts the Bearer token, verifies it with the configured JWT secret, resolves the merchant from the token sub, and attaches the merchant record to req.

I would extend the Express Request type definitions so req.merchant is properly typed across the codebase, then apply the middleware at the router level for all protected merchant, invoice, and future protected route groups instead of duplicating checks per endpoint.

[grantfox-oss]

🦊 GrantFox — @KodeSage has been assigned to this issue as part of the Official Campaign campaign!

Next steps:

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

Good luck! Track your progress on GrantFox.