S292-293: Technical Summary — Vitto Capability System

Date: 2026-03-31 | Branch: session-290-299 | Status: Phase 1+2 complete, pending commit

Security Audit Findings (S292)

Backend-ai-api (port 3001) — CRITICAL

• DecisionService.query() had no userId/spaceId filtering — global data exposure
• LearningController had 1 endpoint with @Roles() out of ~15
• POST /core-rules allowed unauthenticated rule injection
• Pattern promotion endpoint had zero access control

Backend-vitto-api (port 3003) — SERIOUS

• VaultController: all CRUD operations — zero role checks
• Skills CRUD (6 endpoints): zero role checks
• ModuleGenerationController: generate, fullstack, generate-single — zero role checks
• SecurityController: audit reads/exports — zero role checks
• Memory export for arbitrary userIds — zero role checks
• Observability endpoints — @Public() (dev tools publicly accessible)
• GET /compliance/gdpr/export/:userId — exported all personal data with no auth

Backend-api (port 3000) — SOLID WITH GAPS

• Deny-by-default via global UnifiedAuthGuard + RolesGuard
• ~60 controllers rely on service-layer scoping (no explicit @Roles)
• Admin module properly protected
• No critical gaps — service-layer ownership checks provide defense-in-depth

Frontend — BINARY

• DerivedFeatures (15 flags): 0 component usage (dead code)
• All gating via BrainContextService.isAdmin() (binary)
• Sidebar filtering: UI-only, bypassed by direct URL
• GoGrab-dev: no role restrictions except 1 endpoint

Architecture Decisions

1. Capability Matrix (Single Source of Truth)

@libs-foundational/core-models/src/lib/capabilities/
├── capability.enum.ts      — VittoCapability (85 values, 9 categories)
├── capability.types.ts     — CapabilityDefinition, CapabilityOverride, CapabilityResolution
├── capability-matrix.ts    — CAPABILITY_MATRIX constant + CAPABILITY_MAP (O(1) lookup)
├── capability-resolver.ts  — resolveCapability(), hasCapability(), getAllCapabilities(), etc.
├── capability-resolver.spec.ts — 15 unit tests
├── __tests__/capability-matrix-integrity.spec.ts — 183 integrity tests
└── index.ts

2. Three-Decorator Model

3. Three-Tier Override Resolution

userOverride > spaceOverride > matrixDefault
(non-overridable capabilities skip overrides entirely)

4. Guard Chain (APP_GUARD order)

UnifiedAuthGuard → RolesGuard → CapabilityGuard

CapabilityGuard skips if @Public, @Authenticated, or no @RequireCapability metadata (backward compat).

Implementation Inventory

Phase 1: Foundation (14 new files, 9 modified)

Pure Logic Layer:

• capability.enum.ts — 85 capabilities across 9 categories
• capability-matrix.ts — Full metadata: key, category, scope, risk, description, allowedRoles, overridable
• capability-resolver.ts — 3-tier resolution, category helpers, matrix access
• capability-resolver.spec.ts + capability-matrix-integrity.spec.ts — 198 tests

Backend Guard Layer:

• authenticated.decorator.ts — @Authenticated() via SetMetadata
• capability.decorator.ts — @RequireCapability() via SetMetadata
• capability.guard.ts — CapabilityGuard with normalizeToPlatformRole()
• capability-validator.service.ts — Startup scanner via ModulesContainer
• capability.guard.spec.ts — 57 guard tests (all roles × capabilities × edge cases)

Frontend Signal Layer:

• role-access.service.ts — RoleAccessService with can(), can$(), 12 pre-computed signals
• capability.guard.ts — capabilityGuard() CanActivateFn factory

Critical Endpoint Enforcement (58 decorators):

• vault.controller.ts — class-level MANAGE_VAULT
• security.controller.ts — 13 decorators (VIEW_AUDIT_LOGS, EXPORT_AUDIT_LOGS, VIEW_COMPLIANCE, ENFORCE_RETENTION, GDPR_DELETE, RESET_RATE_LIMITS)
• module-generation.controller.ts — 13 decorators (TRIGGER_MODULE_GEN, TRIGGER_FULLSTACK_GEN, VIEW_GEN_STATUS)
• vitto.controller.ts — 9 skill decorators (CREATE/EDIT/DELETE/PUBLISH/GENERATE_SKILL, INSTALL_SKILL)
• learning.controller.ts — 17 decorators (VIEW_CORE_RULES, EDIT_CORE_RULES, VIEW_PATTERNS, PROMOTE_PATTERN)

Phase 2: Feature Wiring (7 new files, 4 modified)

Mind Features Controller (10 endpoints):

• Knowledge Graph: GET /engine/mind/graph, /graph/stats, /graph/search
• Thought Trace: GET /engine/mind/traces/recent, /traces/:taskId
• Memory Health: GET /engine/mind/health, /stale-memories, /consolidation-preview
• Triggers: POST /engine/mind/consolidate, /decay

Override Storage:

• capability-override.schema.ts — MongoDB schema with TTL, unique compound index
• capability-override.service.ts — CRUD with upsert pattern
• capability-override.controller.ts — REST API at /engine/capabilities (MANAGE_USER_PERMISSIONS)

Frontend Migration:

• Shell sidebar: adminOnly replaced with requiredCapability + RoleAccessService.can()
• Routes: capabilityGuard() on 8 routes (3 Mind + 5 Developer)
• App routes: capabilityGuard() on 3 Mind feature routes in gograb-ai
• Capability Matrix Table: standalone component with filters, search, export

Test Coverage

Bugs Found and Fixed

Files Changed (Complete List)

New Files (21)

libs/libs-foundational/core-models/src/lib/capabilities/capability.types.ts
libs/libs-foundational/core-models/src/lib/capabilities/capability.enum.ts
libs/libs-foundational/core-models/src/lib/capabilities/capability-matrix.ts
libs/libs-foundational/core-models/src/lib/capabilities/capability-resolver.ts
libs/libs-foundational/core-models/src/lib/capabilities/capability-resolver.spec.ts
libs/libs-foundational/core-models/src/lib/capabilities/__tests__/capability-matrix-integrity.spec.ts
libs/libs-foundational/core-models/src/lib/capabilities/index.ts
libs/libs-api/auth-core/src/lib/decorators/authenticated.decorator.ts
libs/libs-api/auth-core/src/lib/decorators/capability.decorator.ts
libs/libs-api/auth-core/src/lib/guards/capability.guard.ts
libs/libs-api/auth-core/src/lib/guards/__tests__/capability.guard.spec.ts
libs/libs-api/auth-core/src/lib/validators/capability-validator.service.ts
libs/libs-foundational/auth-core/src/lib/role-access/role-access.service.ts
libs/libs-foundational/auth-core/src/lib/role-access/capability.guard.ts
libs/libs-foundational/auth-core/src/lib/role-access/index.ts
APIs/backend-vitto-api/src/app/mind/mind-features.controller.ts
APIs/backend-vitto-api/src/app/mind/schemas/capability-override.schema.ts
APIs/backend-vitto-api/src/app/engine/capability-override.service.ts
APIs/backend-vitto-api/src/app/engine/capability-override.controller.ts
libs/libs-ai/vitto-hub/src/lib/components/capability-matrix/capability-matrix-table.component.ts
libs/libs-ai/vitto-hub/src/lib/components/capability-matrix/capability-matrix-table.component.html
libs/libs-ai/vitto-hub/src/lib/components/capability-matrix/capability-matrix-table.component.scss
docs/english/sessions/S292/292-293-capability-system-progress-report.md
docs/english/sessions/S292/292-293-technical-summary.md
docs/superpowers/specs/2026-03-31-vitto-capability-system-and-enhancements-design.md
docs/superpowers/plans/2026-03-31-vitto-capability-system-phase1.md
docs/superpowers/plans/2026-03-31-vitto-capability-system-phase2.md

Modified Files (13)

libs/libs-foundational/core-models/src/lib/utils/index.ts
libs/libs-api/auth-core/src/lib/auth-core.module.ts
libs/libs-api/auth-core/src/index.ts
libs/libs-foundational/auth-core/src/index.ts
APIs/backend-vitto-api/src/app/security/vault.controller.ts
APIs/backend-vitto-api/src/app/security/security.controller.ts
APIs/backend-vitto-api/src/app/module-generation/module-generation.controller.ts
APIs/backend-vitto-api/src/app/engine/vitto.controller.ts
APIs/backend-vitto-api/src/app/engine/engine.module.ts
APIs/backend-vitto-api/src/app/mind/mind.module.ts
APIs/backend-ai-api/src/app/learning/learning.controller.ts
libs/libs-ai/vitto-hub/src/lib/routes/vitto-hub.routes.ts
libs/libs-ai/vitto-hub/src/lib/components/vitto-unified-shell/vitto-unified-shell.component.ts
apps/gograb-ai/src/app/app.routes.ts

Remaining Work (Phases 3-4)

Phase 3: Full Migration + Intelligence Layering

• Migrate ~60 backend-api controllers to @Authenticated()/@RequireCapability()
• Add userId/spaceId filtering to DecisionService.query() and EpisodicMemoryService
• Intelligence data visibility by role (pyramid view per role)
• Core Layer Management Dashboard (executive only)
• Capability Permission Editor UI (executive only)

Phase 4: New Features + Strict Enforcement

• Space Capability Configuration (builder tool)
• Personal Preferences Panel (all users)
• Startup validator → strict mode (CI enforcement: CAPABILITY_AUDIT=strict)
• Deprecate @Roles() in favor of @RequireCapability()
• Deprecate DerivedFeatures and BrainContextService.isAdmin()