Skip to main content

FR-01 — IAM Security Design

Introduction​

The FR-01 IAM Security Design defines the security controls required to protect SalesFam user identities, credentials, authentication sessions, account recovery, onboarding, and access to protected resources. It ensures that only verified and authorized users can access the functions and data associated with their account and role.

Scope​

The IAM security design covers:

  • Password and credential protection
  • Email verification security
  • Authentication security
  • Session and refresh-token security
  • Password recovery security
  • Rate limiting and abuse protection
  • Account-status enforcement
  • Role-based access control
  • Resource ownership protection
  • Guest access boundaries
  • Sensitive-data protection
  • Server-side input validation
  • Secure authentication error handling

1. Security Objective​

The IAM security design protects user identities, credentials, authentication sessions, and access to SalesFam resources. The design must ensure that Identity → Authentication → Authorization → Protected Resource cannot be bypassed by manipulating client-side data, tokens, IDs, or account state.

2. Password Security​

Passwords must never be stored or returned in plaintext.

Design:

  • Store only a strong password hash.
  • Use a modern password-hashing algorithm such as bcrypt or Argon2id.
  • Never return passwordHash through an API response.
  • Do not log passwords or credentials.
  • Apply a password policy during registration and reset.

Rule: Password → (Argon2id or bcrypt) → passwordHash.

3. Email Verification Code Security​

Verification codes are temporary credentials and must be protected.

Design:

  • Generate a cryptographically secure random code.
  • Make each code time-limited.
  • Store only a protected representation of the code.
  • Mark the code as used after successful verification.
  • Invalidate previous active codes when a new code is issued.
  • Limit verification attempts.
  • Limit resend frequency.

Lifecycle: Generated → Active → Used or Expired. A verification code must never be reusable.

4. Authentication Security​

Login must be validated entirely on the server.

Design: the server must verify, in order: email → user exists → password matches → account status permits login → authenticated session created. Client-side role information must never determine authentication or authorization.

5. Access Token & Refresh Session Security​

For the MVP, use a short-lived access token plus a longer-lived refresh session. The refresh credential should be treated as a sensitive secret.

Recommended model: Login → short-lived Access Token + Refresh Session. The refresh credential should preferably be stored in a Secure, HttpOnly cookie for the web application rather than exposed to JavaScript. The server stores only the protected form of the refresh credential.

Session lifecycle: ACTIVE → REFRESHED → EXPIRED or REVOKED.

6. Logout Security​

Logout must invalidate the corresponding refresh session — a deleted client-side token alone is not sufficient.

Logout → Session revoked → Refresh request rejected. The access token should naturally become unusable once its short lifetime expires.

7. Password Reset Security​

Password-reset credentials must be temporary and single-use.

Design:

  • Generate a cryptographically secure reset credential.
  • Store only its protected representation.
  • Apply a short expiration period.
  • Invalidate it after successful use.
  • Never expose the existing password.
  • Revoke existing sessions after a successful password reset.

Flow: Forgot Password → Reset Credential → Validate → New Password → Reset Credential Used → Existing Sessions Revoked.

8. Rate Limiting & Abuse Protection​

Authentication endpoints are high-risk endpoints and require rate limiting. At minimum, protect /auth/register, /auth/verify, /auth/verify/resend, /auth/login, /auth/refresh, /auth/forgot-password, /auth/reset-password.

Rate limits should apply especially to repeated login failures, verification attempts, verification-code resends, password-reset requests, and password-reset attempts. The goal is to prevent brute-force attacks, credential stuffing, and email/code abuse.

9. Account Status Enforcement​

Account status must be checked server-side for protected operations: ACTIVE → allowed, SUSPENDED → denied, DEACTIVATED → denied. A suspended or deactivated account must not regain access simply by using an existing token. Where appropriate, account suspension should also revoke active sessions.

10. RBAC Security​

Role-based access control must be enforced on the backend. Supported roles: COMPANY, REP, ADMIN. The client must never be trusted to determine role, userId, companyId, repId, or permissions. The server obtains the authenticated identity and verifies authorization before every protected operation.

11. Resource Ownership Protection​

RBAC alone is insufficient. The server must verify that the authenticated user has access to the specific resource being requested.

Example: Company A → Company A order (allowed); Company A → Company B order (denied); Rep A → Rep A commission (allowed); Rep A → Rep B commission (denied). Changing an ID in a request must never grant access.

12. Guest Security Boundary​

Guest access must remain separate from authenticated access. A Guest may access designated public functionality, but cannot access Company resources, Rep resources, Admin resources, private orders, commission data, or financial data. The server must enforce this boundary, not the frontend.

13. Cookie, CORS & Transport Security​

All authentication traffic must use HTTPS in deployed environments. For browser-based authentication:

  • Authentication cookies should use HttpOnly where applicable.
  • Cookies should use Secure.
  • Appropriate SameSite policy must be configured.
  • CORS must allow only trusted frontend origins.
  • Credentials must not be accepted from arbitrary origins.

14. Sensitive Data Protection​

The following must never appear in normal API responses or logs: password, password hash, verification code, verification code hash, password-reset token, password-reset token hash, refresh token, refresh-token hash. Only the minimum required identity information should be returned to the client.

15. Input Validation​

All IAM inputs must be validated server-side — email format, password requirements, verification-code format, account type, reset credentials, required onboarding fields. Client-side validation improves usability, but server-side validation is authoritative.

16. Security Error Handling​

Authentication and recovery endpoints should avoid exposing sensitive information. For example, forgot-password should not reveal "This email does not exist." Instead: "If the account exists, password recovery instructions have been sent." This prevents account enumeration.

17. Summary​

FR-01 Security Principles:

  1. Never trust the client.
  2. Never store plaintext credentials.
  3. Keep temporary credentials short-lived and single-use.
  4. Authenticate before authorization.
  5. Enforce authorization on the server.
  6. Check resource ownership, not only roles.
  7. Rate-limit authentication flows.
  8. Protect refresh credentials.
  9. Revoke sessions when security-sensitive events require it.
  10. Expose only the minimum necessary information.

FR-01 Security Boundary: