Sessions Security & Unification — Design Spec

Date: 2026-03-16 Session: S227 (implementation) Status: Draft — Awaiting Approval Scope: All 4 backends + frontend session infrastructure Risk Level: Foundation-level — pre-production (no real users)

Executive Summary

The GoGrab session infrastructure has 8 distinct session schemas, 84+ session-related endpoints across 4 APIs, 70 unguarded controllers (47%), 5 distinct guard implementations (with incompatible request.user shapes), and no global authentication on any backend. Whistle (group chat) endpoints are @Public() with self-asserted caller identity. Inter-service tokens use inconsistent variable names. The tenantId field exists in schemas but is never populated.

This spec defines a unified security and session architecture that:

1. Locks down all backends with a global UnifiedAuthGuard (deny-by-default)
2. Creates dedicated /internal/* routes for service-to-service communication (Option B)
3. Formalizes tenantId = spaceId across all schemas and endpoints
4. Hardens whistle/group chat with proper authentication and tenant isolation
5. Consolidates duplicate endpoints and dead code
6. Gives Vitto secure cross-tenant aggregation for its Jarvis-like intelligence

Part 1: Unified Auth Guard (APP_GUARD)

Problem

No backend registers a global guard. Every controller without @UseGuards() is fully public. 70 of 150 controllers have no class-level guard. The existing @Public() soft-auth pattern in JwtAuthGuard works well — but only when the guard is actually applied.

Additionally, 5 distinct guard classes exist with incompatible request.user shapes:

• BackendAuthGuard (APIs/backend-api/src/app/backend-auth/backend-auth.guard.ts) — sets req.user.sub (raw JWT sub claim)
• JwtAuthGuard (libs/libs-api/auth-core/src/lib/guards/jwt-auth.guard.ts) — sets req.user.userId (normalized from sub)
• InfrastructureAuthGuard (APIs/backend-ai-api/src/app/infrastructure/guards/infrastructure-auth.guard.ts) — adds isLocalhostBypass, isApiKeyAuth, userType
• ProjectApiKeyGuard (APIs/backend-ai-api/src/app/mcp-gateway/guards/project-api-key.guard.ts) — API key validation
• TierLimitGuard (APIs/backend-ai-api/src/app/mcp-gateway/guards/tier-limit.guard.ts) — billing guard reading user.spaceId, user.mcpTier

Additionally, ComputerUsePermissionGuard (APIs/backend-ai-api/src/app/infrastructure/guards/computer-use-permission.guard.ts) is a permission guard that must be audited for compatibility with UnifiedCaller.

Live bug: AiAgentsController in backend-api uses BackendAuthGuard but reads req.user.userId — always undefined.

Design

1.1 Global Guard Registration

Register UnifiedAuthGuard as APP_GUARD in AuthCoreModule.forRoot() on all 4 backends:

// libs/libs-api/auth-core/src/lib/auth-core.module.ts
providers: [
  { provide: APP_GUARD, useClass: UnifiedAuthGuard },
  { provide: APP_GUARD, useClass: RolesGuard },  // runs after UnifiedAuthGuard
]

This means every route is protected by default. Routes that need to be public must explicitly use @Public(). This inverts the current model (open by default, guard opt-in) to closed by default, public opt-in.

1.2 Authentication Strategies (tried in order)

Strategy 1: Service JWT (Bearer svc_*)        → CallerType.SERVICE
Strategy 2: User JWT (Bearer <jwt>)           → CallerType.USER
Strategy 3: System Token (Bearer <static>)    → CallerType.SERVICE (backward compat)
Strategy 4: API Key (X-MCP-API-Key header)    → CallerType.API_KEY
Strategy 5: Localhost bypass (dev-only, NODE_ENV !== 'production')
            → CallerType.DEV

If @Public() is on the route: skip auth failure, but still decode token if present (soft-auth). This preserves existing behavior for guest/anonymous endpoints.

1.3 Unified Caller Interface

Every request.user conforms to one shape:

interface UnifiedCaller {
  // Identity
  userId: string;            // MongoDB _id, 'svc:vitto-api', or 'apikey:{ownerId}'
  sub: string;               // ALIAS for userId — backward compat
  email?: string;
  displayName?: string;

  // Classification
  callerType: 'user' | 'service' | 'api-key' | 'dev';
  serviceName?: string;      // 'vitto-api', 'ai-api', etc.

  // Authorization
  roles: string[];
  platformRole?: string;     // executive, developer, admin, etc.
  permissions: string[];     // fine-grained: 'sessions:read', 'sessions:write:own'
  scopes: string[];          // service scopes: 'sessions:read:all', 'users:read:all'

  // Tenant context
  tenantId?: string;         // = spaceId
  spaceId?: string;          // alias for tenantId

  // Auth metadata
  authMethod: 'jwt' | 'service-jwt' | 'system-token' | 'api-key' | 'localhost';
  isApiKeyAuth: boolean;     // backward compat for InfrastructureAuthGuard consumers
  isLocalhostBypass: boolean; // backward compat
  mcpTier?: string;
  userType?: string;
}

Critical: sub and userId are both set to the same value as plain object properties (NOT getter aliases — getters break JSON serialization for logging/forwarding). Both always have the same value. This means zero changes to the ~80 backend-api controller methods reading req.user.sub.

1.4 Custom Decorators

@CallerType('user')            // Only human users
@CallerType('service')         // Only internal services
@CallerType('user', 'service') // Both
@ServiceOnly()                 // Shorthand for @CallerType('service')
@TenantScoped()                // Guard verifies caller has access to the tenantId in the request
@OwnerOnly()                   // Guard verifies req.user.userId matches the resource's userId

Default when no @CallerType() applied: Any authenticated caller type is allowed (user, service, api-key, dev). @CallerType() is a narrowing decorator that restricts access — not a widening one.

1.5 Guard Replacement Map

Kept (not auth guards — update to use UnifiedCaller):

• RolesGuard — role hierarchy check. Works on request.user set by unified guard.
• TierLimitGuard — billing. Must update to read UnifiedCaller.mcpTier and UnifiedCaller.spaceId (currently reads undocumented fields from raw payload).
• ThrottlerGuard — rate limiting. Independent.

1.6 @Public() Audit

After APP_GUARD is registered, every currently-unguarded controller becomes protected. We must audit all 70 unguarded controllers and:

• Add @Public() to routes that are intentionally public (health checks, webhooks, auth entry points, customer-facing)
• Leave undecorated (now protected) for routes that were accidentally unguarded

Known intentionally-public routes to preserve:

• Health endpoints (/health, AppController health methods)
• Auth entry points (MagicLinkController, PhoneAuthController)
• Webhook receivers (StripeWebhookController — uses Stripe HMAC in service layer)
• Customer-facing (CustomerController in vitto-api)
• MCP JSON-RPC (McpJsonRpcController — uses its own API key in protocol)
• Observatory/awareness SSE (ObservatoryController, AwarenessController)
• A2A discovery (GET .well-known/agent.json)
• DocsSyncController, AdminController in backend-docs-api (must be included in audit)

Routes that should become protected (currently accidentally public):

• BenchmarkController — DB benchmarks with no auth
• StudioGitController (backend-api) — GitLab push/delete with no auth
• ConnectorController — API keys/secrets management with no auth
• TrainingController — Agent training with no auth
• PlatformGenerationController — Full generation pipeline with no auth
• SuperIntelligenceController — Intelligence CRUD with no auth
• SecurityController — Has @Roles() without @UseGuards(JwtAuthGuard) — broken
• All other controllers listed in the guard audit

Scope Warning: The @Public() audit is not "review 70 controllers." vitto.controller.ts alone is 4,061 lines with 114 @Public() annotations. The real scope is **300+ route methods** across all backends. The S227.2 phase must be broken into per-backend sub-tasks:

• S227.2a: backend-api (67 controllers, ~3 @Public())
• S227.2b: backend-ai-api (62 controllers, ~65 @Public())
• S227.2c: backend-vitto-api (21 controllers, ~85+ @Public() — vitto.controller.ts dominates)
• S227.2d: backend-docs-api (needs inventory)

Prerequisite note: vitto.controller.ts (4,061 lines, ~114 @Public() annotations) is a god-controller that makes security auditing extremely error-prone. It should be decomposed into domain-specific controllers (similar to how VittoCoreController was already extracted) as a parallel track. This decomposition is not blocking for the guard rollout, but significantly reduces the risk of the @Public() audit.

1.7 SSE Authentication Strategy

Browser EventSource API cannot send HTTP headers — this is why many Vitto endpoints are @Public() with soft-auth. This is a fundamental browser limitation, not a design oversight.

Solution: Ticket-based SSE auth.

1. Client calls an authenticated POST endpoint to request a short-lived opaque ticket
2. Backend stores { ticket, userId, tenantId, expiresAt } (TTL 30s, single-use)
3. Client opens SSE with ?ticket=<token> query parameter
4. SSE endpoint validates the ticket, deletes it (single-use), and sets request.user
5. If no valid ticket, SSE returns 401

// New endpoint (protected by JWT via APP_GUARD)
@Post('sse-ticket')
async createSseTicket(@CurrentUser() user: UnifiedCaller): Promise<{ ticket: string }> {
  return this.sseAuthService.createTicket(user.userId, user.tenantId);
}

// SSE endpoint (still @Public() but validates ticket)
@Public()
@Sse('stream')
async stream(@Query('ticket') ticket: string): Observable<MessageEvent> {
  const user = await this.sseAuthService.consumeTicket(ticket);
  if (!user) throw new UnauthorizedException('Invalid or expired SSE ticket');
  // ... proceed with authenticated SSE stream
}

Phase 1 (S227): Keep existing @Public() SSE endpoints working. Add ticket-based auth as an optional enhancement. Phase 2 (post-S227): Require tickets on all SSE endpoints. Remove raw @Public().

This pattern is well-established (Mercure, Firebase, etc.) and avoids the polyfill approach of wrapping EventSource.

1.8 "Temporarily Public" Cleanup

PlatformAIController in backend-ai-api has 4 methods with "Temporarily public for development" comments. These must be audited: remove @Public() if the frontend sends JWT, or convert to @CallerType('service') if only called by other backends.

Part 2: Internal Service Endpoints (Option B)

Problem

Vitto needs cross-user, cross-tenant data access to build its Jarvis-like intelligence. Today, it calls the same endpoints that users call, authenticated with SYSTEM_TOKEN. This creates two problems:

1. Same endpoint must serve two incompatible authorization models (per-user vs cross-tenant)
2. Token confusion: SYSTEM_TOKEN vs BACKEND_API_INTERNAL_TOKEN — same value, different env vars, easy misconfiguration

Design

2.1 Internal Route Prefix

Each backend gets a /internal/* route prefix with dedicated controllers:

backend-api:      /api/internal/...
backend-ai-api:   /ai-api/internal/...
backend-vitto-api: /vitto-api/internal/...

These routes are:

• Protected by @CallerType('service') — only service JWTs or system tokens
• Optimized for aggregation (batch queries, tenant-scoped, no per-user filtering)
• Not exposed in API documentation or client SDKs

2.2 Service Identity

Replace the static SYSTEM_TOKEN pattern with short-lived service JWTs:

// Service JWT payload
interface ServiceJwtPayload {
  iss: string;        // 'vitto-api', 'ai-api', 'backend-api'
  sub: string;        // 'svc:vitto-api'
  serviceName: string;
  scopes: string[];   // ['sessions:read:all', 'users:read:tenant']
  tenantId?: string;  // optional tenant constraint
  iat: number;
  exp: number;        // 5 minute lifetime
}

Phase 1 (S227): Keep SYSTEM_TOKEN working via Strategy 3 in UnifiedAuthGuard. This is backward-compatible.

Phase 2 (future): Migrate connectivity clients to generate short-lived service JWTs signed with a shared secret. This eliminates the static token risk.

The shared secret (SERVICE_JWT_SECRET) is a new env var, distinct from JWT_SECRET (user tokens) and SYSTEM_TOKEN (legacy).

2.3 Internal Endpoint Inventory

backend-ai-api internal routes for Vitto:

GET  /ai-api/internal/sessions/tenant/:tenantId          → All sessions for a space
GET  /ai-api/internal/sessions/tenant/:tenantId/genomes  → All genomes for a space
GET  /ai-api/internal/sessions/user/:userId               → All sessions for a user (cross-tenant)
GET  /ai-api/internal/sessions/:id                        → Any session by ID (no ownership check)
POST /ai-api/internal/sessions/:id/messages               → Append as any user (Vitto injecting system messages)
GET  /ai-api/internal/sessions/search                     → Full-text search across tenant sessions
GET  /ai-api/internal/workflow/sessions/tenant/:tenantId  → Generation sessions for a space
POST /ai-api/internal/embeddings/search                   → Semantic search across tenant data

backend-api internal routes for Vitto/AI-API:

GET  /api/internal/users/:userId                   → User profile
GET  /api/internal/users/tenant/:tenantId           → All users in a space
GET  /api/internal/spaces/:spaceId                  → Space details
GET  /api/internal/spaces/:spaceId/members          → Space member list
GET  /api/internal/modules/:spaceId                 → All modules for a space
POST /api/internal/billing/events                   → Billing event submission

backend-vitto-api internal routes for AI-API:

POST /vitto-api/internal/engine/execute             → Execute a Vitto task
GET  /vitto-api/internal/mind/user/:userId          → User's Vitto memory
GET  /vitto-api/internal/training/tenant/:tenantId  → Training data for a space

2.4 Token Consolidation

Immediate fix: Document that SYSTEM_TOKEN and BACKEND_API_INTERNAL_TOKEN MUST be the same value. Add a startup validation check in each backend.

2.5 Migrate Existing Internal Callers

Part 3: Tenant Model (tenantId = spaceId)

Problem

• tenantId exists in ChatSession and ConfigurationSession schemas but is never populated by the chat flow
• AgentSessionDoc (Vitto) has no tenantId at all — uses spaceId only
• CustomerSession has optional spaceId but no tenantId
• MCP dev sessions have no tenant concept (correct — they're dev tooling)
• Frontend SessionInfo has tenantId? and tenantName? but they're never set

Design

3.1 The Rule

tenantId = spaceId everywhere. These are aliases for the same value. The field name is tenantId in all schemas, but spaceId is accepted as a query alias for backward compatibility.

A user can belong to multiple tenants (spaces). When making a request, the active tenant is determined by:

For CallerType.USER (human users):

1. JWT claim spaceId (if the token is space-scoped)
2. Request body spaceId or tenantId (for creation endpoints)
3. URL parameter :tenantId or :spaceId (for scoped routes)

For CallerType.SERVICE (internal services):

1. Request header X-Tenant-Id (primary — services always specify context)
2. URL parameter :tenantId or :spaceId
3. Request body tenantId

Security restriction: The X-Tenant-Id header is ONLY honored for CallerType.SERVICE callers. User callers sending this header have it ignored. This prevents a compromised browser or user request from overriding JWT-based tenant scoping.

3.2 Schema Changes

3.3 Write-Path Enforcement

Enforce tenantId ↔ spaceId sync at both the schema hook and service layer:

Schema hooks (catch save and update operations):

// Pre-save hook (covers Model.create(), doc.save())
schema.pre('save', function(next) {
  if (this.spaceId && !this.tenantId) this.tenantId = this.spaceId;
  if (this.tenantId && !this.spaceId) this.spaceId = this.tenantId;
  next();
});

// Pre-update hooks (covers findOneAndUpdate, updateMany, etc.)
// NOTE: Mongoose pre-save does NOT fire on updateMany/findOneAndUpdate
schema.pre(['findOneAndUpdate', 'updateMany', 'updateOne'], function(next) {
  const update = this.getUpdate() as any;
  if (update?.$set) {
    if (update.$set.spaceId && !update.$set.tenantId) update.$set.tenantId = update.$set.spaceId;
    if (update.$set.tenantId && !update.$set.spaceId) update.$set.spaceId = update.$set.tenantId;
  }
  next();
});

Service-layer enforcement (primary — more reliable than hooks):

All services that write sessions must call a shared ensureTenantSync(data) utility before any write operation. This is the primary enforcement mechanism — hooks are the safety net.

3.4 Query-Path Changes

All user-facing session list endpoints get an optional tenantId filter:

3.5 Data Migration Script

For existing data (all created by you during testing):

// One-time migration: backfill tenantId from spaceId
db.chat_sessions.updateMany(
  { spaceId: { $exists: true, $ne: null }, tenantId: { $exists: false } },
  [{ $set: { tenantId: '$spaceId' } }]
);

// Backfill spaceId from tenantId where only tenantId exists
db.configuration_sessions.updateMany(
  { tenantId: { $exists: true, $ne: null }, spaceId: { $exists: false } },
  [{ $set: { spaceId: '$tenantId' } }]
);

// Flag sessions missing userId for manual review
// NOTE: Do NOT use sentinel string values in queryable fields — they'd appear in normal queries
db.chat_sessions.updateMany(
  { userId: { $exists: false } },
  { $set: { userId: null, tenantId: null, _needsReview: true } }
);

Part 4: Session Endpoint Consolidation

Problem

84 session-related endpoints across 4 APIs. Many are duplicates, leftovers from the MCP→backend-ai-api evolution, or serve overlapping purposes.

4.1 The 8 Session Concepts (Keep All, Fix Isolation)

None should be merged. They serve genuinely different domains. But all product-facing ones (#3-#7) need tenantId and ownership enforcement.

4.2 Endpoint Rationalization (backend-ai-api)

/ai-api/sessions/* (14 endpoints) — User-Facing Chat Sessions

/ai-api/infrastructure/sessions/* (18 endpoints) — MCP Dev Sessions

These are the MCP development session endpoints. They should be scoped to @CallerType('service', 'dev') since they're only called by MCP tools and admin UIs. They do NOT need tenantId (dev tooling).

/ai-api/workflow/sessions/* (11 endpoints) — Platform Generation Sessions

Already has tenantId required in ConfigurationSession schema. Just needs guard enforcement:

/ai-api/agents/tasks/*/sessions/* (4 endpoints) — Agent Task Sessions

These are task sub-session tracking. Keep with @CallerType('service', 'dev').

4.3 Endpoint Rationalization (backend-api)

/api/ai-agents/session* (18 endpoints) — MCP Sessions on backend-api

These are the backend-api side of MCP dev session management. Many duplicate what /ai-api/infrastructure/sessions/ does:

4.4 Endpoint Rationalization (backend-vitto-api)

Session endpoints on vitto-api are correctly scoped — they're Vitto's own domain:

Part 5: Whistle System Hardening

Problems Found

1. POST /vitto-api/engine/whistle is @Public() — no JWT guard. whistlerUserId comes from request body (self-asserted). Any anonymous caller can whistle anyone.

2. No check that the whistler belongs to the space. Only the target's membership is verified. A caller can claim any spaceId + any whistlerUserId.

3. POST /ai-api/sessions/:id/whistle is @Public() — the backend-ai-api endpoint that upgrades a session to group is also unprotected.

4. allowlist in whistle preferences has no space scope. A flat array of userIds. If a user allows userId X in Space A, X can also whistle them from Space B.

5. WhistleOrchestratorService bypasses typed clients. Uses raw http.post() instead of BackendAiClientService/BackendApiClientService.

6. LLM-initiated whistle is broken. whistle.plugin.ts sends targetUserId: '' — the display-name-to-userId resolution never happens.

Fixes

5.1 Authentication

Remove @Public() from both whistle endpoints:

• POST /vitto-api/engine/whistle — require JWT. whistlerUserId comes from request.user.userId, not body.
• POST /ai-api/sessions/:id/whistle — move to /ai-api/internal/sessions/:id/whistle with @CallerType('service'). Only vitto-api calls this.

5.2 Authorization

Add checkWhistlerMembership() to WhistleOrchestratorService:

// Verify BOTH whistler and target are members of the same space
const members = await this.getSpaceMembers(spaceId);
const whistlerIsMember = members.some(m => m.userId === whistlerUserId);
const targetIsMember = members.some(m => m.userId === targetUserId);

if (!whistlerIsMember) throw new ForbiddenException('Whistler is not a member of this space');
if (!targetIsMember) throw new NotFoundException('Target user is not a member of this space');

Verify spaceId from JWT matches the active space, not from request body.

5.3 Space-Scoped Allowlist

Change whistlePreferences.allowlist from string[] to:

interface WhistleAllowEntry {
  userId: string;
  spaceId?: string;  // null = allowed from any space
}

When spaceId is set, only allow whistle from that specific space. When null, allow from any shared space.

5.4 Use Typed Clients

Replace raw http.post() calls in WhistleOrchestratorService with:

• this.backendApiClient.getSpaceMembers(spaceId) for membership checks
• this.backendAiClient.whistleParticipant(sessionId, data) for session upgrade

5.5 Fix LLM Whistle Tool

In whistle.plugin.ts, add userId resolution from displayName:

// Resolve target user from display name within the active space
const members = await this.backendApiClient.getSpaceMembers(spaceId);
const target = members.find(m =>
  m.displayName?.toLowerCase() === targetName.toLowerCase()
);
if (!target) return { error: `No member named "${targetName}" found in this space` };

Part 6: WebSocket Security

Problem

All 8 WebSocket gateways across 4 backends have no @UseGuards() at class or method level. Authentication is handled ad-hoc in handleConnection() or not at all.

Design

6.1 WebSocket Auth Guard

NestJS APP_GUARD does NOT apply to WebSocket gateways — they use a separate lifecycle. Create a WsAuthGuard that:

1. Extracts JWT from client.handshake.auth.token or client.handshake.query.token
2. Validates the token
3. Sets client.data.user with UnifiedCaller shape
4. Disconnects unauthorized clients

Apply to all gateways that handle user data. Service-to-service gateways (NativeWsGateway, AgentRealtimeGateway) can use service token validation instead.

6.2 Room Isolation

After auth, ensure users only join rooms they're authorized for:

• user:{userId} — only the authenticated user
• chat:{sessionId} — only if user is owner or participant
• space:{spaceId} — only if user is a member of the space
• tenant:{tenantId} — alias for space room

ChatGateway.handleConnection() already does some of this — formalize it and apply to all gateways.

Part 7: Vitto Cross-Tenant Intelligence

The Requirement

Vitto needs to be a Jarvis-like assistant that:

• Remembers all conversations with a user across spaces
• Understands the context of a space (all users, sessions, modules)
• Can correlate patterns across spaces (e.g., "this user has similar issues in Space A and B")
• Can inject system messages into any session (awareness, proactive suggestions)

Design

7.1 Vitto's Service Identity

Vitto authenticates to other backends as svc:vitto-api with scopes:

const vittoScopes = [
  'sessions:read:all',      // Read any session
  'sessions:write:system',  // Write system messages to any session
  'users:read:all',         // Read any user profile
  'spaces:read:all',        // Read any space
  'genomes:read:all',       // Read any conversation genome
  'training:read:all',      // Read training data
  'modules:read:all',       // Read any module
];

7.2 Internal Aggregation Endpoints

Vitto uses /internal/* endpoints (defined in Part 2) to:

1. Build user context: GET /ai-api/internal/sessions/user/:userId → all sessions for a user across all tenants
2. Build tenant context: GET /ai-api/internal/sessions/tenant/:tenantId → all sessions in a space
3. Semantic recall: POST /ai-api/internal/embeddings/search → find relevant past conversations
4. Genome access: GET /ai-api/internal/sessions/tenant/:tenantId/genomes → conversation summaries for a space
5. User enrichment: GET /api/internal/users/:userId → profile, preferences, roles

7.3 Tenant-Scoped Intelligence

When Vitto operates within a space context, it should scope its intelligence:

• Only recall conversations from the current space (unless the user explicitly asks about another space)
• AgentSessionDoc.activeContext.spaceId determines the scope
• Cross-space intelligence requires the user to have membership in both spaces

This prevents Vitto from accidentally leaking Space A data to a user who only has access to Space B.

Part 8: Dead Code & Duplicate Removal

8.1 Duplicate Endpoints to Merge or Remove

8.2 Guard Files to Delete

After UnifiedAuthGuard is deployed:

APIs/backend-api/src/app/backend-auth/backend-auth.guard.ts              → DELETE
APIs/backend-ai-api/src/app/infrastructure/guards/infrastructure-auth.guard.ts → DELETE
APIs/backend-ai-api/src/app/mcp-gateway/guards/project-api-key.guard.ts  → DELETE

Keep but audit:

APIs/backend-ai-api/src/app/infrastructure/guards/computer-use-permission.guard.ts → KEEP (update field access for UnifiedCaller)
APIs/backend-ai-api/src/app/mcp-gateway/guards/tier-limit.guard.ts                → KEEP (update field access for UnifiedCaller)

8.3 Token Variable Cleanup

Part 9: Implementation Phases

Phase 1: Foundation (S227.1–S227.4)

S227.1 — UnifiedAuthGuard + UnifiedCaller interface

• Create UnifiedAuthGuard in @libs-api/auth-core
• Register as APP_GUARD in AuthCoreModule.forRoot()
• Create UnifiedCaller interface and @CallerType(), @ServiceOnly(), @TenantScoped(), @OwnerOnly() decorators
• Test with a single backend first (backend-ai-api)

S227.2 — @Public() audit across all backends (~300+ route methods)

• S227.2a: backend-api (67 controllers, ~3 existing @Public())
• S227.2b: backend-ai-api (62 controllers, ~65 existing @Public())
• S227.2c: backend-vitto-api (21 controllers, ~85+ existing @Public())
• S227.2d: backend-docs-api (inventory + audit)
• Add @Public() to intentionally-public routes
• Remove per-controller @UseGuards() from all 80+ controllers that had them
• Remove "Temporarily public" annotations from PlatformAIController
• Delete old guard files
• IMPORTANT: Fix auth headers on WhistleOrchestratorService.checkSpaceMembership() in this phase — it calls GET /spaces/:spaceId/members without Bearer token, which will break when APP_GUARD goes live on backend-api. This must be fixed BEFORE or DURING the backend-api audit, not deferred to S227.5.

S227.3 — Tenant model enforcement

• Add tenantId to AgentSessionDoc, CustomerSession
• Add pre-save hooks for tenantId ↔ spaceId sync
• Add optional tenantId query parameter to user-facing list endpoints
• Run data migration script on dev databases

S227.4 — Internal endpoints (Phase 1)

• Create /internal/* controllers on backend-ai-api and backend-api
• Move cross-user query endpoints to internal
• Update vitto-api connectivity clients to use internal routes
• Keep SYSTEM_TOKEN for auth (Phase 1)

Phase 2: Hardening (S227.5–S227.7)

S227.5 — Whistle hardening

• Remove @Public() from whistle endpoints
• Add whistler membership check
• Space-scope the allowlist
• Route whistle through typed clients
• Fix LLM whistle tool userId resolution

S227.6 — Ownership enforcement on session endpoints

• Add @OwnerOnly() or participant check to:
  • GET /sessions/:id
  • DELETE /sessions/:id
  • POST /sessions/:id/whistle
  • GET /sessions/:id/participants
  • POST /sessions/:id/messages
  • POST /sessions/:id/reconcile
  • GET /sessions/:id/genome

S227.7 — WebSocket security

• Create WsAuthGuard
• Apply to ChatGateway, RealtimeGateway
• Add room isolation checks
• Service gateways: validate service token in handleConnection()

Phase 3: Cleanup (S227.8–S227.9)

S227.8 — Endpoint consolidation

• Merge duplicate infrastructure session endpoints
• Deprecate/remove unfiltered /sessions/history
• Remove migration/debugging endpoints from production API surface
• Remove deprecated guard files

S227.9 — Token consolidation & documentation

• Add startup token validation assertions
• Fix McpUsageService to use typed client with auth
• Fix PlatformOrchestrationService token variable name
• Document the auth architecture in docs/english/GoGrab-Space/architecture/

Phase 4: Future (Post-S227)

• Service JWTs: Replace static SYSTEM_TOKEN with short-lived signed JWTs
• Fine-grained permissions: Expand permissions[] and scopes[] for granular access control
• Audit logging: Log all service-to-service calls with caller identity and tenant context
• Rate limiting per tenant: TierLimitGuard reads tenantId for per-space quotas

Risk Assessment

Rollback Strategy

If APP_GUARD registration causes unacceptable breakage during development:

1. Immediate: Revert the APP_GUARD registration in auth-core.module.ts (single line change)
2. Re-add per-controller @UseGuards() to the controllers that previously had them (git history)
3. Keep new @Public() annotations — they're harmless without a global guard
4. Keep new internal endpoints and UnifiedCaller interface — they work independently

This rollback is safe because:

• The @Public() additions are no-ops without a global guard
• Internal endpoints are additive (new controllers, not modifications)
• The UnifiedCaller interface is consumed only by code we control

The rollback window closes after all backends are verified working with APP_GUARD. After that, the per-controller guards are deleted and rollback requires a full revert.

Success Criteria

1. Zero unguarded controllers — every route is either @Public() (intentionally) or JWT-protected
2. All session schemas have tenantId — populated on every write
3. Ownership checks on all session-by-ID endpoints — no cross-user data leakage
4. Whistle requires authentication — no self-asserted identity
5. Internal routes exist and are used — Vitto calls /internal/* with service identity
6. One auth guard class — UnifiedAuthGuard replaces BackendAuthGuard, InfrastructureAuthGuard, and ProjectApiKeyGuard
7. Token consistency — startup validation prevents misconfiguration
8. WebSocket gateways authenticate connections — no anonymous real-time access

Files to Create

libs/libs-api/auth-core/src/lib/guards/unified-auth.guard.ts
libs/libs-api/auth-core/src/lib/guards/ws-auth.guard.ts
libs/libs-api/auth-core/src/lib/decorators/caller-type.decorator.ts
libs/libs-api/auth-core/src/lib/decorators/tenant-scoped.decorator.ts
libs/libs-api/auth-core/src/lib/decorators/owner-only.decorator.ts
libs/libs-api/auth-core/src/lib/decorators/service-only.decorator.ts
libs/libs-api/auth-core/src/lib/interfaces/unified-caller.interface.ts
APIs/backend-ai-api/src/app/internal/internal-sessions.controller.ts
APIs/backend-ai-api/src/app/internal/internal.module.ts
APIs/backend-api/src/app/internal/internal-users.controller.ts
APIs/backend-api/src/app/internal/internal-spaces.controller.ts
APIs/backend-api/src/app/internal/internal.module.ts
APIs/backend-vitto-api/src/app/internal/internal-engine.controller.ts
APIs/backend-vitto-api/src/app/internal/internal.module.ts
scripts/migrations/backfill-tenant-id.ts

Files to Delete

APIs/backend-api/src/app/backend-auth/backend-auth.guard.ts
APIs/backend-ai-api/src/app/infrastructure/guards/infrastructure-auth.guard.ts
APIs/backend-ai-api/src/app/mcp-gateway/guards/project-api-key.guard.ts

Files to Modify (Major Changes)

libs/libs-api/auth-core/src/lib/auth-core.module.ts          — Register APP_GUARD
libs/libs-api/auth-core/src/lib/guards/jwt-auth.guard.ts     — Refactor into UnifiedAuthGuard
~150 controller files                                          — Remove @UseGuards() or add @Public()
APIs/backend-vitto-api/src/app/engine/whistle-orchestrator.service.ts — Auth + typed clients
APIs/backend-vitto-api/src/app/tools/plugins/whistle.plugin.ts       — Fix LLM whistle
APIs/backend-vitto-api/src/app/connectivity/*.ts                     — Use internal routes
APIs/backend-ai-api/src/app/sessions/sessions.controller.ts          — Ownership checks
APIs/backend-ai-api/src/app/sessions/sessions.schema.ts              — tenantId enforcement
APIs/backend-vitto-api/src/app/mind/schemas/agent-session.schema.ts  — Add tenantId
APIs/backend-vitto-api/src/app/mind/schemas/customer-session.schema.ts — Add tenantId
APIs/backend-ai-api/src/app/mcp-gateway/services/mcp-usage.service.ts — Replace fetch() with typed client