154 lines
2.8 KiB
Markdown
154 lines
2.8 KiB
Markdown
Blockers & Guards
|
|
|
|
This document defines clear, non-overlapping responsibilities for Blockers (frontend) and Guards (backend).
|
|
The goal is to prevent semantic drift, security confusion, and inconsistent implementations.
|
|
|
|
⸻
|
|
|
|
Core Principle
|
|
|
|
Guards enforce. Blockers prevent.
|
|
• Guards protect the system.
|
|
• Blockers protect the UX.
|
|
|
|
There are no exceptions to this rule.
|
|
|
|
⸻
|
|
|
|
Backend — Guards (NestJS)
|
|
|
|
Definition
|
|
|
|
A Guard is a backend mechanism that enforces access or execution rules.
|
|
If a Guard denies execution, the request does not reach the application logic.
|
|
|
|
In NestJS, Guards implement CanActivate.
|
|
|
|
⸻
|
|
|
|
Responsibilities
|
|
|
|
Guards MAY:
|
|
• block requests entirely
|
|
• return HTTP errors (401, 403, 429)
|
|
• enforce authentication and authorization
|
|
• enforce rate limits
|
|
• enforce feature availability
|
|
• protect against abuse and attacks
|
|
|
|
Guards MUST:
|
|
• be deterministic
|
|
• be authoritative
|
|
• be security-relevant
|
|
|
|
⸻
|
|
|
|
Restrictions
|
|
|
|
Guards MUST NOT:
|
|
• depend on frontend state
|
|
• contain UI logic
|
|
• attempt to improve UX
|
|
• assume the client behaved correctly
|
|
|
|
⸻
|
|
|
|
Common Backend Guards
|
|
• AuthGuard
|
|
• RolesGuard
|
|
• PermissionsGuard
|
|
• ThrottlerGuard (NestJS)
|
|
• RateLimitGuard
|
|
• CsrfGuard
|
|
• FeatureFlagGuard
|
|
|
|
⸻
|
|
|
|
Summary (Backend)
|
|
• Guards decide
|
|
• Guards enforce
|
|
• Guards secure the system
|
|
|
|
⸻
|
|
|
|
Frontend — Blockers
|
|
|
|
Definition
|
|
|
|
A Blocker is a frontend mechanism that prevents an action from being executed.
|
|
Blockers exist solely to improve UX and reduce unnecessary requests.
|
|
|
|
Blockers are not security mechanisms.
|
|
|
|
⸻
|
|
|
|
Responsibilities
|
|
|
|
Blockers MAY:
|
|
• prevent multiple submissions
|
|
• disable actions temporarily
|
|
• debounce or throttle interactions
|
|
• hide or disable UI elements
|
|
• prevent navigation under certain conditions
|
|
|
|
Blockers MUST:
|
|
• be reversible
|
|
• be local to the frontend
|
|
• be treated as best-effort helpers
|
|
|
|
⸻
|
|
|
|
Restrictions
|
|
|
|
Blockers MUST NOT:
|
|
• enforce security
|
|
• claim authorization
|
|
• block access permanently
|
|
• replace backend Guards
|
|
• make assumptions about backend state
|
|
|
|
⸻
|
|
|
|
Common Frontend Blockers
|
|
• SubmitBlocker
|
|
• AuthBlocker
|
|
• RoleBlocker
|
|
• ThrottleBlocker
|
|
• NavigationBlocker
|
|
• FeatureBlocker
|
|
|
|
⸻
|
|
|
|
Summary (Frontend)
|
|
• Blockers prevent execution
|
|
• Blockers improve UX
|
|
• Blockers reduce mistakes and load
|
|
|
|
⸻
|
|
|
|
Clear Separation
|
|
|
|
Aspect Blocker (Frontend) Guard (Backend)
|
|
Purpose Prevent execution Enforce rules
|
|
Security ❌ No ✅ Yes
|
|
Authority ❌ Best-effort ✅ Final
|
|
Reversible ✅ Yes ❌ No
|
|
Failure effect UI feedback HTTP error
|
|
|
|
|
|
⸻
|
|
|
|
Naming Rules (Hard)
|
|
• Frontend uses *Blocker
|
|
• Backend uses *Guard
|
|
• Never mix the terms
|
|
• Never implement Guards in the frontend
|
|
• Never implement Blockers in the backend
|
|
|
|
⸻
|
|
|
|
Final Rule
|
|
|
|
If it must be enforced, it is a Guard.
|
|
|
|
If it only prevents UX mistakes, it is a Blocker. |