Auth Service

Owns accounts and sessions. It registers users, logs them in, and hands out JWT access and refresh tokens as httpOnly cookies. The access token it signs is what every other service trusts, so its JWT_ACCESS_SECRET has to match the rest of the platform.

• Port: 3001
• Routes: /api/auth/* (register, login, logout, refresh-token, me, verify-email, forgot-password, reset-password, change-password)

Running

npm install
npm run dev     # live reload
npm run build   # compile to dist/

Environment (.env)

PORT=3001
MONGO_URI=<mongodb connection string>
FRONTEND_URL=http://localhost:5173
GATEWAY_URL=http://localhost:3000

JWT_ACCESS_SECRET=<shared with all services>
JWT_REFRESH_SECRET=<secret>
JWT_ACCESS_EXPIRY=15m
JWT_REFRESH_EXPIRY=7d
SERVICE_AUTH_SECRET=<shared with all services>

COOKIE_SECURE=false
COOKIE_SAMESITE=lax

Folder layout

src/
  config/       db connection, plan entitlements
  controllers/  route handlers
  errors/       error factories (createUnauthorizedError, ...)
  middleware/   auth, validation, error handler
  models/       Mongoose schemas
  routes/       Express routers
  validators/   request body schemas
  index.ts      entry point

Errors are thrown as typed factory errors and turned into JSON by a single middleware. ERROR_HANDLING_GUIDE.md explains the pattern with examples.