fleetforge/docs/adrs/004-authentication.md

ADR-004: Authentication Model

Status

Accepted

Context

The platform needs secure authentication for both admin users and device agents.

Decision

• Admin users: JWT-based authentication with bcrypt password hashes
• Device agents: Unique credential per device, stored as SHA-256 hashes in the database
• Enrollment: Time-limited, optionally single-use tokens, also stored as hashes

Rationale

• JWTs are stateless, simple to implement, and work well with REST APIs
• Device credentials are long-lived but can be rotated
• Token hashing prevents database compromise from revealing usable credentials
• Role-based authorization with hierarchy: owner > admin > operator > read_only

Consequences

• JWT secret must be configured via environment variable
• Tokens should have reasonable expiry (24h default for users)
• Device credentials are generated during enrollment and stored securely
• All auth decisions are logged to the audit trail