Architecture: How should the three-decorator model work for endpoint acces...

Documentation for Sessions

🏗️ Architecture: How should the three-decorator model work for endpoint acces...

Date: 2026-03-31
Time: 18:41:54 UTC
Session: gspace1-293.3
Agent: backend
Confidence: 93%
Status: ✅ Documented

📋 Decision Context

Question:

How should the three-decorator model work for endpoint access control across all backends?

Task: S292-293: Three-decorator endpoint protection model

🎯 Decision Made

Chosen:

Three explicit decorators: @Public() (no auth), @Authenticated() (JWT required, any role), @RequireCapability(VittoCapability.X) (JWT + specific capability). Every endpoint MUST have exactly one. Startup validator CapabilityValidatorService enforces completeness.

Options Considered:

  1. Two decorators: @Public and @RequireCapability (force all authenticated endpoints to have a capability)
  2. Three decorators: @Public, @Authenticated, @RequireCapability (separate auth-only from capability-gated)
  3. No new decorators: enhance existing @Roles to support capabilities

💭 Reasoning

Many endpoints (chat, own profile, own preferences) need authentication but shouldn't require specific capabilities — they're available to ANY logged-in user. Forcing a fake BASIC_ACCESS capability on ~200+ endpoints would pollute the matrix and create noise. The three-decorator model cleanly separates: public (health, auth flows), authenticated (own-data, browsing), and capability-gated (admin features). The startup validator uses NestJS ModulesContainer to scan all controllers and their method prototypes for decorator metadata — this catches gaps at boot time rather than in production. CapabilityGuard runs AFTER existing RolesGuard as APP_GUARD, maintaining backward compatibility during migration.

📁 Files Involved

🔗 Related

Auto-generated by MCP Smart Consolidation