Skip to main content

Security Design Philosophy

Framework M is built on the principle of "Invisible Guardrails". We believe that a secure application should be the default, and developers should only have to intervene when they need to explicitly relax a security constraint.

The Problem with Traditional CSRF​

Many frameworks rely on Synchronizer Tokens. In this pattern, the server generates a unique token for every session (or every request) and expects the client to send it back in a header or form field.

While secure, this introduces several "cliffs":

  1. State Dependency: It requires a session store (Redis/DB) to verify a simple POST request, making stateless APIs harder to scale.
  2. Developer Friction: Every frontend request must manually "grab" and "inject" the token.
  3. Cache Blocking: Injecting tokens into HTML prevents effective CDN caching.

The Framework M Approach: Stateless Origin-Check​

Framework M implements an Origin-based CSRF defense. This relies on the browser's guaranteed behavior of sending the Origin or Referer header on cross-site requests.

Why Origin-based?​

  1. Stateless & High-Performance: Verification is a simple string comparison against allowed domains. No database lookups required.
  2. Browser Guarantees: Modern browsers ensure that Origin and Referer headers cannot be spoofed by client-side Javascript from another domain.
  3. Seamless Integration: It works "out of the box" for cURL, mobile apps, and service-to-service calls because these clients are immune to cross-site hijacking and don't trigger the browser-specific guardrails.

The Double-Lock Strategy​

秉 CSRF Double-Lock Strategy 秉

We combine Origin-checking with SameSite Cookie Policies:

  • First Lock (SameSite=Lax): Our session cookies are restricted such that the browser will not send them on cross-site POST requests.
  • Second Lock (Origin Check): If the cookie somehow bypasses the restriction, the CSRF middleware validates the source.

Pluggable Architecture​

Following our Hexagonal philosophy, the security logic is defined via the CSRFProtocol. If an application requires a more invasive security model (e.g., Token-based checks or Proof-of-Work headers), the default DefaultCSRFAdapter can be swapped for a custom adapter via the Dependency Injection container.

[!TIP] This design ensures that Framework M remains a high-performance toolkit suitable for both single-user tools and massive, distributed SaaS platforms.