Security is applied at every layer -from identity to data storage to transport.

Related: Authentication · Database · API Reference · Production Hardening · Deployment · Back to README

• Firebase Authentication is the sole identity provider. The onAuthStateChanged listener blocks all protected UI until the auth state resolves.
• Every API route verifies the Firebase ID token from the Authorization: Bearer <token> header using the Firebase Admin SDK.
• On 401, the client-side store force-refreshes the token and retries once. On second 401, the user is signed out.

See authentication.md for the full Firebase Auth flow.

Seven roles are defined: company_admin, super_admin, company_manager, operations_manager, fleet_manager, dispatcher, driver. Role is stored server-side in the UserRecord MongoDB document and never derived from client input.

Role matrix enforcement is handled by requireWorkforceRead, requireWorkforceWrite, and requireUserMgmt helpers in src/lib/auth-helpers.ts.

companyId is resolved exclusively from the authenticated user's UserRecord. No API route accepts companyId from the request body or query parameters. Every MongoDB query in multi-tenant collections filters by companyId.

Cross-company leakage at the transport layer is structurally impossible -Socket.io company rooms are joined using the server-side companyId, not client-provided values.

Driver and vehicle detail endpoints verify that the fetched document's companyId matches the requesting user's companyId. Mismatches return HTTP 403 with the message "Access denied: resource belongs to a different company.". Cross-company resource access is structurally blocked.

aadhaarNumber on Driver records is encrypted at rest using AES-256-GCM before MongoDB storage. The encryption key is read from DATA_ENCRYPTION_KEY (a 32-byte base64 value). Non-manager roles receive the value masked as "****" in API responses.

Zod schemas validate every inbound API payload before any downstream logic executes. Validation failures return HTTP 400 with field-level error messages. OSRM, OpenWeather, Gemini, and MongoDB are never called when validation fails.

The Shipment Pass includes a SHA-256 hash of the route decision data computed at dispatch time. The hash is tamper-evident by design. Any modification to the route fields after dispatch would produce a different hash.

CompanyAudit and WorkforceAudit records are insert-only. No API endpoint updates or deletes audit records. The workforce_audits collection has no update or delete paths anywhere in the codebase. createWorkforceAuditEvent wraps the insert in try/catch and logs failures but never re-throws -audit write failures never break the primary operation.

All collections have compound indexes that enforce uniqueness (shipmentId, driverId, vehicleId, auditId) and support tenant-scoped queries (companyId prefix on all workforce indexes). This prevents accidental cross-tenant data leakage from partial queries.