Critical Insight: Ensuring ESHOPMAN API Field Restrictions Are Enforced

Understanding ESHOPMAN's API Field Restriction Behavior

As an e-commerce platform built on Node.js/TypeScript, ESHOPMAN offers robust capabilities for headless commerce, including powerful Admin API and Store API endpoints. Developers often rely on configurations like http.restrictedFields and route-level allowed query parameters to precisely control what data is exposed through these APIs. This is crucial for security, performance, and maintaining a clean data contract, especially when deploying custom storefronts via HubSpot CMS.

However, a recent community insight has highlighted an important nuance: these critical API data governance features might not be active by default, leading to unexpected behavior where configured restrictions are silently ignored.

The Unexpected Behavior

Developers configuring ESHOPMAN to restrict certain fields from being returned in API responses – for instance, preventing sensitive customer or order details from being exposed on public store routes – may find that these restrictions are not being enforced. For example, if you configure your ESHOPMAN instance to restrict orders data on a store route, a request like ?fields=orders.… would still return the order details, instead of stripping them out or returning an error.

This can create a false sense of security and potentially expose data that was intended to be private or accessible only to specific roles via the Admin API.

Why It Happens: The Undocumented Feature Flag

The core of this issue lies in how ESHOPMAN currently gates the enforcement of these field restrictions. While the system correctly identifies and computes the fields that should be restricted or allowed based on your eshopman-config.js, the final step of actually applying these rules (either by stripping the fields or returning an error) is conditionally tied to an internal, undocumented feature flag.

Specifically, the enforcement logic is currently dependent on the MEDUSA_FF_RBAC_FILTER_FIELDS environment variable. Without this flag explicitly enabled, the system calculates the violations but then discards them, effectively bypassing your configured restrictions.

Impact on ESHOPMAN Developers and Merchants

• For Developers: If you've implemented custom logic or rely on ESHOPMAN's built-in restrictedFields for API data control, you need to be aware that these might not be active. This could necessitate manual data filtering or lead to unintended data exposure in your HubSpot CMS-deployed storefronts or integrated applications.
• For Merchants: Understanding this behavior is vital for maintaining data security and compliance. If your ESHOPMAN setup is intended to restrict certain data points from public access, verifying this configuration is crucial.

Immediate Workaround: Enabling the Feature Flag

To ensure your http.restrictedFields and route-level allowed configurations are actively enforced in your ESHOPMAN instance, you must explicitly enable the feature flag. This is done by setting an environment variable in your ESHOPMAN server's environment:

MEDUSA_FF_RBAC_FILTER_FIELDS=true

After setting this environment variable, restart your ESHOPMAN server. Your configured field restrictions should now be actively applied to API requests.

For example, in your eshopman-config.js, you might have:

module.exports = {  // ... other configurations  http: {    restrictedFields: {      store: ["order", "orders", "customer.email"], // Example: Restrict these on Store API      admin: ["user.passwordHash"] // Example: Restrict this on Admin API    }  },  // ...};

With MEDUSA_FF_RBAC_FILTER_FIELDS=true, these restrictions will now be enforced.

Looking Ahead

This insight underscores the importance of clear documentation for platform features, especially those related to security and data governance. While the current workaround is effective, the ESHOPMAN community anticipates that these fundamental API control mechanisms will eventually be decoupled from internal feature flags and enforced by default, aligning with developer expectations and best practices for headless commerce API design.

Stay tuned to the ESHOPMAN community for updates and further best practices on securing and optimizing your headless commerce platform!