61 lines
1.6 KiB
Markdown
61 lines
1.6 KiB
Markdown
# Blockers and Guards (Shared Contract)
|
|
|
|
This document defines the **shared contract** for Blockers (website UX) and Guards (API enforcement).
|
|
|
|
If a more specific document conflicts with this one, this shared contract wins.
|
|
|
|
Related:
|
|
|
|
- API authorization: [`docs/architecture/api/AUTHORIZATION.md`](docs/architecture/api/AUTHORIZATION.md:1)
|
|
- Website delivery-layer contract: [`docs/architecture/website/WEBSITE_CONTRACT.md`](docs/architecture/website/WEBSITE_CONTRACT.md:1)
|
|
|
|
## 1) Core principle (non-negotiable)
|
|
|
|
Guards enforce. Blockers prevent.
|
|
|
|
- Guards protect the system.
|
|
- Blockers protect the UX.
|
|
|
|
There are no exceptions.
|
|
|
|
## 2) Definitions (strict)
|
|
|
|
### 2.1 Guard (API)
|
|
|
|
A Guard is an **API mechanism** that enforces access or execution rules.
|
|
|
|
If a Guard denies execution, the request does not reach application logic.
|
|
|
|
### 2.2 Blocker (Website)
|
|
|
|
A Blocker is a **website mechanism** that prevents an action from being executed.
|
|
|
|
Blockers exist solely to improve UX and reduce unnecessary requests.
|
|
|
|
Blockers are not security.
|
|
|
|
## 3) Responsibility split (hard boundary)
|
|
|
|
| Aspect | Blocker (Website) | Guard (API) |
|
|
|---|---|---|
|
|
| Purpose | Prevent execution | Enforce rules |
|
|
| Security | ❌ No | ✅ Yes |
|
|
| Authority | ❌ Best-effort | ✅ Final |
|
|
| Reversible | ✅ Yes | ❌ No |
|
|
| Failure effect | UX feedback | HTTP error |
|
|
|
|
## 4) Naming rules (hard)
|
|
|
|
- Website uses `*Blocker`.
|
|
- API uses `*Guard`.
|
|
- Never mix the terms.
|
|
- Never implement Guards in the website.
|
|
- Never implement Blockers in the API.
|
|
|
|
## 5) Final rule
|
|
|
|
If it must be enforced, it is a Guard.
|
|
|
|
If it only prevents UX mistakes, it is a Blocker.
|
|
|