Authentication and authorization
High-level behavior (implementation lives in ethica-api).
Staff
- Staff users authenticate to access the ERP (and related tooling).
- Sessions and MFA credentials are modeled in the database (see
StaffSession,StaffMfaCredential, etc.). - Permissions are attached to roles and optionally per-user overrides (
Role,Permission,RolePermission,UserPermission).
Customers
- Customer portal accounts use dedicated models (
CustomerPortalAccount,CustomerSession,CustomerMfaCredential, …). - Separation between staff and customer auth paths avoids privilege bleed.
- Recovery codes (one-time backups for lost authenticator devices) are documented in Customer MFA and recovery codes. End-user wording lives under Operations — Customer portal recovery codes.
API enforcement
- Controllers should enforce authorization on every sensitive route; document new permission keys when you add them.
Configuration (names only — see ethica-api/.env.example)
These variables tune lifetimes and crypto behavior; never commit real values to git or this doc.
| Area | Variables | Purpose |
|---|---|---|
| JWT (staff) | JWT_SECRET, JWT_EXPIRES_IN | Signing key and access-token lifetime (seconds; default aligns with session expectations). |
| Session idle | SESSION_IDLE_MINUTES | Idle timeout for staff sessions (works with JWT expiry). |
| Password hashing | BCRYPT_SALT_ROUNDS | Work factor for password hashes. |
| Staff MFA | MFA_ENCRYPTION_KEY, MFA_STEP_UP_HOURS, MFA_ISSUER_NAME, MFA_DISABLED, SKIP_MFA_IN_DEV, MFA_DEV_ALWAYS_STEP_UP, MFA_ENFORCEMENT_REQUIRED | TOTP secrets encryption, step-up window, issuer label, and environment-specific MFA toggles. |
| Customer MFA | CUSTOMER_MFA_ISSUER, CUSTOMER_MFA_ENCRYPTION_KEY | Separate issuer label and encryption material for customer TOTP. |
Cookie names, rotation details, and exact token storage are defined in application code—update this section when you publish a security review or client-specific notes.