Appendix — Backend Middleware
CEO Summary
Middleware runs on every request before the route handler. Auth, tenant resolution, rate limiting, and validation are enforced here. Order matters: tenantResolver must run before auth; auth before feature gates.
Auth & Session
| File | Purpose |
|---|---|
| sessionAuth.js | requireSessionAuth — Requires req.session.user.id. Sets req.user. 401 if missing. |
| mysqlSessionAuth.js | MySQL-backed session auth variant |
| flexibleAuth.js | requireFlexibleAuth — Accepts session OR API key OR other auth |
| auth.js | Base auth utilities |
| authRequired.js | Legacy auth required |
| requireAuth.js | Generic require auth |
| apiAuth.js | API key authentication |
| deviceAuth.js | Device key auth for kiosk/mobile |
Tenant & Org
| File | Purpose |
|---|---|
| tenantResolver.js | Resolves req.tenant from session, headers, API key, subdomain |
| tenant.js | Tenant utilities |
| orgResolver.js | Org resolution |
| masterAdminTenantAccess.js | Master admin tenant access control |
Authorization & Permissions
| File | Purpose |
|---|---|
| authorize.js | Authorization checks |
| requireRoles.js | Role-based access |
| requirePerm.js | Permission-based access |
| requireScope.js | Scope-based access |
| roles.js | Role definitions |
| staffPermissions.js | Staff permission checks |
| featureGate.js | checkFeatureAccess(module) — Plan/feature gates |
Tickets
| File | Purpose |
|---|---|
| requireTicketRole.js | Ticket role requirement |
| attachTicketRole.js | Attach ticket role to request |
| ticketRateLimit.js | Rate limit for ticket endpoints |
| ticketIPWhitelist.js | IP whitelist for tickets |
Rate Limiting
| File | Purpose |
|---|---|
| rateLimiter.js | General rate limiter (used on /api) |
| rateLimiterAdv.js | Advanced rate limiting |
| rateLimit.js | Rate limit middleware |
| rateByKey.js | Rate limit by key |
Request & Error
| File | Purpose |
|---|---|
| requestId.js | Add req.id for tracing |
| requestLogger.js | Request logging |
| errorHandler.js | Error handling |
| globalErrorHandler.js | Global error handler |
| notFound.js | 404 handler |
Other
| File | Purpose |
|---|---|
| validate.js | Request validation (Joi) |
| idempotency.js | POS/sync idempotency: Idempotency-Key + optional X-PPO-* headers; sets req.ppoMutation; dedupes replayed offline/bridge requests |
| auditLogger.js | Audit logging |
| security.js | Security headers, etc. |
| safeQuery.js | Safe query execution |
| employeeResolver.js | Resolve employee from request |
| autoCreateStaff.js | Auto-create staff when needed |
| apiCompatibility.js | API response compatibility layer |
Middleware Order (server.js)
Global order: CORS → body parsers → session → requestId → requestLogger → rateLimiter (on /api) → route-specific (tenantResolver, requireSessionAuth, etc.)