Design Decision Note

[metalalive]

Role-Based Access Control & Permissions

How does the system enforce the role-based access control across different API endpoints in any application ?

• when a user is assigned a role, all the low-level permissions associated with the role will be updated to JWT payload during the next token refresh.
• each API endpoint in an application extracts permission data from the JWT payload once the user is authenticated, validates whether the token contains all necessary permissions required to access the endpoint.

What are the advantages and potential pitfalls of having roles manage low-level permissions instead of directly assigning permissions to users?

Advantages

• Roles are easier to manage access rights to multiple users at once, changes to one single permission will automatically propagate to all roles applying it and all users applying that roles.
• Roles allow to group permission logically, for platform staff it is straightforward to examine role definitions rather than individual permissions. When the system grows, it reduces administrative overhead.
• Roles can be tied to group for the inheritance of permissions. this is useful especially in organizations where responsibilities are divided across departments or teams.

Potential pitfalls

• update delay, when a role is updated with different set of permissions, the changes are not immediately reflect to other applications, authenticated users have to refresh their JWT token to receive updated permissions.
• indirect troubleshooting, diagnosing access issues can be more challenging. Debugging often requires tracing the role hierarchy to understand the effective permissions for a given user.
• over-privileging risk, If roles are not carefully designed, they might bundle more permissions than necessary, potentially granting users broader access than required (violating the principle of least privilege)

Quota Management

How is quota management integrated into the system ?

• this application maintains limits (quota arrangement) associated with various types of resources (e.g., maximum emails, phone numbers .. etc) available among the system and different users / groups.
• these limits can be assigned directly to user profiles, or inherited from groups.
• when quota arrangements are updated, the changes are incorporated to users' JWT payload during the next token refresh, ensuring other applications immediately enforce the new limits.

How would the system handle a situation where a user’s direct quota arrangements conflict with inherited quota values from their group ?

• in current design, the arrangement direct to a user take precedence over the one inherited from groups.

JWT and Authentication:

how JWT token creation, signing, and refresh are implemented in this application?

• when a user logs in successfully, this application issues a new JWT token specifically for refreshing purpose
• signing process for a JWT token relies on configurable keystore helper, internally the token is encoded and signed using asymmetry cryptography (currently RSA256).
• for token refresh, an authenticated user sends a JWT refresh token to this application, after validation it generates and returns another JWT access token, which includes user profile ID, assigned permissions, and quota arrangements.

How does the system manage JWKS rotation

This application manages JWKS rotation through a configurable keystore helper.

• a keystore loads cryptographic private keys to sign JWT tokens when a token is created or refreshed
• the corresponding public keys are made available through a JWKS endpoint. other applications can retrieve the latest public keys and verify incoming JWT tokens.
• when keys need to be rotated, the keystore adds new keys and conditionally removes keys which reach expiry time.
• during the rotation window, this application must support tokens signed with both the old and new keys until rotation is completed.

what challenges might arise with JWKS management ?

• Synchronization: Ensuring that all other applications fetch the updated public keys is critical. Caching at the client or intermediary layers might lead to verification failures if outdated keys are used.
• Token Validity: In current implementation, this application does not maintain backward compatibility so that tokens signed with previous keys become invalid if the key expires.
• Security: automating key rotation without service disruption and ensuring private keys remain confidential in storage are ongoing challenges.

In what ways does the authentication flow protect against replay attacks or token misuse ?

This application mitigates possibility of replay attacks with following strategies :

• use short-lived access tokens, minimizing the window during which a stolen token can be reused.
• use long-live refresh tokens, longer lifespan allows users to obtain new access tokens when needed without compromising security.
• secure token storage, such as
  • httpOnly cookies to prevent XSS
  • or browser memory and frontend app must not expose any token (by logging them or passing them to untrusted 3rd-party libraries, to prevent leakage)

Planned enhancement, TODO :

• nonce in the authentication request, then can be included in JWT payload, see (explanation).
• revocation list, record blacklist of tokens abandoned but not expired yet, allowing system to invalidate tokens immediately.

Additional consideration :

• although this project focuses only on backend dev and have not been deployed with any frontend application in production environment, enforcing secure transport such as TLS v1.3 also reduces chances of man-in-middle attack.
• currently I don't consider one-time use token (e.g. add jti field to JWT) , I haven't found any situation that requires it.

Asynchronous Processing:

What happens if an asynchronous task (e.g., email notifications, user profile query) fails, and how is that failure handled?

• RPC consumers returns the error back to application, then the application responds with simplified error (strip out sensitive detail, to avoid exposing credential) to clients , it does not block response to clients.
• this system logs and monitors severe errors with detailed information (such as exception type, message, and context) for future troubleshooting or manual intervention.
• no retry logic in the asynchronous tasks, this application leaves the decision to application callers which initiates the RPC.

Failure in each asynchronous task does not lead to data inconsistency or system downtime.

• if an email fails to send, the user's account state remains unchanged, and the failure can be handled independently
• the user profile search in asynchronous task is a read-only operation so it does not modify any data.
• if a keystore fails to rotate keys, this application continues to use old set of keys until next rotation event occurs

General Design Considerations:

What trade-offs did you consider when designing the separation between authentication data (login accounts) and user profile data?

• Security : by isolating login credentials in a dedicated authentication model, the risk of exposing sensitive data can be reduced when handling user profile information. Also enables stricter security policies for credentials without affecting other user data
• Maintainability and Extensibility:
  • in many cases, this application operates with either authentication model or user profile, separating these concerns allows each model to evolve independently.
  • the authentication model can remain lean and focused on login and token management
  • the user profile model can be extended with additional detail such as contact, group memberships, roles, and quotas arrangement.
• Complexity: such separation introduces complexity only in few operations like account activation and password reset, these do not expect to cause significant performance issues.

How does the system prevent malicious activities such as email enumeration or unauthorized account resets?

• Uniform Responses, endpoints related to account recovery (e.g., username or password reset) always return a generic success status (e.g. HTTP 202 Accepted), regardless of whether the email exists in the system. This prevents attackers from inferring the existence of an account based on differing responses.
• Token-Based Verification, for account resets, a secure, hashed token is generated and sent to the user's email. This token is required to authorize the reset, and its validity (including expiry) is strictly enforced. If the token is invalid or expired, the system rejects the request without revealing any sensitive details.
• One-Time Use and Invalidation, once a reset token is used, it is invalidated to prevent replay attacks. This ensures that an old token cannot be reused to perform another reset.

How the system integrates with external applications (e.g., product, storefront, order-processing) through the user-management API?

TODO