RBAC Hardening & Expansion

[Systemsaholic]

Summary

• Unified @AdminOnly() decorator — consolidated 3 inconsistent admin guard patterns across 10 controllers
• Public endpoint audit — fixed class-level @Public() on AppController, gated debug-sentry behind admin
• Platform settings guard — locked Stripe/settings endpoints to admin
• Contact access filtering — linked-data endpoints (trips, bookings, payments) gated by ownership for agents, "Limited View" badge + "Request Access" button in UI
• Dashboard agent filtering — getStats() scoped to agent's trips/contacts, revenue suppressed for non-admins
• Role display rename — "User" → "Agent" across admin UI
• Security audit logging — new security_audit_logs table + SecurityAuditService + exception filter for login_failed/access_denied/role_changed events
• Contact share request workflow — new contact_share_requests table, create/approve/deny flow with notifications, 30-day expiry
• Impersonation system — new impersonation_sessions table, ImpersonationGuard with session lock + full context swap, 30min sessions (4hr max), frontend banner with countdown, audit trail + agent notification

Database Migrations

• 20260320120000_create_security_audit_logs (idx 162)
• 20260320120100_create_contact_share_requests (idx 163)
• 20260320120200_create_impersonation_sessions (idx 164)

Test plan

• Verified on tf-demo preview environment
• Impersonation tested in browser: start → banner shown → admin features blocked → agent-scoped data → exit → admin restored
• Role display shows "Agent" instead of "User"
• Zero new TypeScript errors (only pre-existing)
• All old guard patterns removed (grep verified)
• Sentry issue [Sentry] PostgresError: relation "impersonation_sessions" does not exist #58 fixed (graceful table-missing handling)
• Manual QA: contact share request flow (request → owner notification → approve/deny)

Spec

docs/superpowers/specs/2026-03-20-rbac-hardening-design.md

🤖 Generated with Claude Code

Summary by CodeRabbit

Release Notes

• New Features

  • Added contact access request workflow—users can now request access to contacts from owners
  • Added admin impersonation capability with session management and expiration controls
  • Added "Limited View" badge for contacts with restricted access

• Bug Fixes

  • Improved email authentication failure handling with clearer error messages and credential update prompts
  • Fixed contact data filtering to properly restrict sensitive information for users without full access

• Enhancements

  • Enhanced security audit logging for tracking administrative actions and access control events

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
tailfire-client	Ready	Preview, Comment	Mar 20, 2026 6:49pm
tailfire-ota	Ready	Preview, Comment	Mar 20, 2026 6:49pm

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: bd626d66-9ce2-43e3-aaad-16ff9044cf10

📥 Commits

Reviewing files that changed from the base of the PR and between 0cbe1f4 and 279c7d2.

📒 Files selected for processing (61)

• apps/admin/src/app/contacts/[id]/_components/contact-share-request-button.tsx
• apps/admin/src/app/contacts/[id]/page.tsx
• apps/admin/src/app/emails/inbox/page.tsx
• apps/admin/src/app/profile/_components/email-tab.tsx
• apps/admin/src/app/providers.tsx
• apps/admin/src/app/settings/users/_components/users-table.tsx
• apps/admin/src/app/settings/users/page.tsx
• apps/admin/src/components/impersonation/impersonation-banner.tsx
• apps/admin/src/hooks/use-emails.ts
• apps/admin/src/hooks/use-impersonation.ts
• apps/admin/src/lib/api.ts
• apps/admin/src/lib/constants/roles.ts
• apps/api/src/api-credentials/api-credentials.controller.ts
• apps/api/src/app.controller.ts
• apps/api/src/app.module.ts
• apps/api/src/auth/decorators/admin-only.decorator.ts
• apps/api/src/auth/decorators/bypass-impersonation.decorator.ts
• apps/api/src/auth/guards/impersonation.guard.ts
• apps/api/src/automation/admin/automation.controller.ts
• apps/api/src/contacts/contact-access.service.ts
• apps/api/src/contacts/contact-share-requests.controller.ts
• apps/api/src/contacts/contact-share-requests.service.ts
• apps/api/src/contacts/contacts.controller.ts
• apps/api/src/contacts/contacts.module.ts
• apps/api/src/contacts/dto/contact-share-request.dto.ts
• apps/api/src/dashboard/dashboard.controller.ts
• apps/api/src/dashboard/dashboard.service.ts
• apps/api/src/email-accounts/email-accounts.service.ts
• apps/api/src/email-accounts/email-sync.processor.ts
• apps/api/src/email-accounts/imap-sync.service.ts
• apps/api/src/enrichment/enrichment.controller.ts
• apps/api/src/external-apis/providers/aerodatabox/aerodatabox.controller.ts
• apps/api/src/financials/commission/commission.controller.ts
• apps/api/src/financials/stripe-connect.controller.ts
• apps/api/src/impersonation/impersonation.controller.ts
• apps/api/src/impersonation/impersonation.module.ts
• apps/api/src/impersonation/impersonation.service.ts
• apps/api/src/loyalty-programs/loyalty-programs.controller.ts
• apps/api/src/main.ts
• apps/api/src/notifications/listeners/notification-events.listener.ts
• apps/api/src/notifications/notification.service.ts
• apps/api/src/notifications/notification.types.ts
• apps/api/src/reference-data/reference-data.controller.ts
• apps/api/src/security-audit/security-audit.module.ts
• apps/api/src/security-audit/security-audit.service.ts
• apps/api/src/security-audit/security-audit.types.ts
• apps/api/src/security-audit/security-exception.filter.ts
• apps/api/src/suppliers/suppliers.controller.ts
• apps/api/src/trips/trips.controller.ts
• apps/api/src/users/users.controller.ts
• apps/api/src/users/users.service.ts
• docs/superpowers/specs/2026-03-20-rbac-hardening-design.md
• packages/database/src/migrations/20260320120000_create_security_audit_logs.sql
• packages/database/src/migrations/20260320120100_create_contact_share_requests.sql
• packages/database/src/migrations/20260320120200_create_impersonation_sessions.sql
• packages/database/src/migrations/meta/_journal.json
• packages/database/src/schema/contact-share-requests.schema.ts
• packages/database/src/schema/impersonation-sessions.schema.ts
• packages/database/src/schema/index.ts
• packages/database/src/schema/security-audit-logs.schema.ts
• packages/shared-types/src/api/contacts.types.ts

---

📝 Walkthrough

Walkthrough

This PR implements a comprehensive RBAC hardening and expansion system, introducing: a standardized @AdminOnly() decorator for admin authorization across the API, a new impersonation system allowing admins to assume user contexts, a contact share request workflow for agent-to-agent contact access, and security audit logging for security events. Additionally, email authentication failures are now handled more gracefully with specific error codes and UI notifications.

Changes

Cohort / File(s)	Summary
Impersonation Frontend apps/admin/src/components/impersonation/impersonation-banner.tsx, apps/admin/src/hooks/use-impersonation.ts	New client-side impersonation system: banner component displays active session status with extend/exit controls and countdown timer; hook manages session state via API calls, localStorage persistence, 30s polling, and automatic page reload on session end.
Impersonation Backend apps/api/src/impersonation/*, apps/api/src/auth/guards/impersonation.guard.ts, apps/api/src/auth/decorators/bypass-impersonation.decorator.ts	Complete impersonation infrastructure: controller exposes start/extend/end/status endpoints, service manages session lifecycle with 4-hour max duration and agency validation, guard validates impersonation context and rewrites request.user, bypass decorator marks endpoints exempt from context swapping.
Authorization Refactoring apps/api/src/auth/decorators/admin-only.decorator.ts, apps/api/src/*/...-controller.ts (15+ files)	Unified @AdminOnly() decorator standardizes admin authorization across API by replacing scattered @UseGuards(AdminGuard) and @Roles('admin') patterns on ~25 controller methods and class-level declarations.
Contact Share Requests System apps/api/src/contacts/contact-share-requests.*, apps/admin/src/app/contacts/[id]/_components/contact-share-request-button.tsx, apps/admin/src/app/contacts/[id]/page.tsx	New agent-to-agent contact access request workflow: frontend button initiates POST to share-requests endpoint with loading/success states; backend service validates ownership/access, prevents duplicates (30-day expiration), emits events; controller exposes create/list/resolve endpoints; access service now includes _accessLevel field on responses.
Security Audit Logging apps/api/src/security-audit/*, apps/api/src/auth/guards/...	New security event logging: SecurityAuditService listens for security.* events and persists to database; SecurityExceptionFilter captures 401/403 exceptions and emits audit events; UsersService emits role change events; ImpersonationService and ContactShareRequestsService emit related events.
Email Authentication Error Handling apps/admin/src/app/emails/inbox/page.tsx, apps/admin/src/app/profile/_components/email-tab.tsx, apps/api/src/email-accounts/imap-sync.service.ts, apps/api/src/email-accounts/email-sync.processor.ts, apps/api/src/hooks/use-emails.ts	IMAP authentication failures now detected and handled with specific error code 'IMAP_AUTH_FAILED': frontend shows destructive alert with credential update link; backend centralizes failure handling with HttpException throwing; error state persists to account; email sync skips on auth failures.
Database Schema packages/database/src/migrations/202603201201..., packages/database/src/schema/*.schema.ts	Three new tables: impersonation_sessions (admin-user pairs, expiry, end reason), contact_share_requests (request workflow with pending/approved/denied states and 30-day expiration), security_audit_logs (event audit trail with metadata); all with appropriate indexes and constraints.
Frontend Access Control & UI apps/admin/src/app/providers.tsx, apps/admin/src/app/settings/users/_components/users-table.tsx, apps/admin/src/app/settings/users/page.tsx, apps/admin/src/lib/constants/roles.ts	UI enhancements: ImpersonationBanner added to provider tree; users table includes impersonate action for admins on non-admin targets; role display names standardized via getRoleDisplayName() helper; useUser hook integration for admin/role checks.
Infrastructure & Types apps/api/src/app.module.ts, apps/api/src/main.ts, apps/api/src/lib/api.ts, packages/shared-types/src/api/contacts.types.ts	Global guard registration adds ImpersonationGuard in correct order; SecurityAuditModule and ImpersonationModule wired into AppModule; ApiError extended with optional code field; getAuthHeaders now includes X-Impersonate-User-Id header from localStorage; ContactResponseDto includes _accessLevel field.
Documentation docs/superpowers/specs/2026-03-20-rbac-hardening-design.md	Design specification documenting RBAC hardening standardization, contact share requests workflow, impersonation system architecture, security audit logging, endpoint authorization audit requirements, and out-of-scope items.

Sequence Diagram(s)

sequenceDiagram
    participant Admin as Admin User
    participant UI as Frontend UI
    participant API as API Server
    participant DB as Database
    participant Events as Event System

    Admin->>UI: Click "Impersonate User"
    UI->>API: POST /admin/impersonate/{userId}
    API->>DB: Create impersonation_session
    API->>Events: Emit security.impersonation_started
    Events->>DB: Log security audit event
    API-->>UI: Session details + expiresAt
    UI->>UI: Store impersonate-user-id in localStorage
    UI->>UI: Redirect to /dashboard
    
    Note over UI: ImpersonationBanner appears<br/>with countdown timer
    
    Admin->>UI: Click "Extend" (before expiry)
    UI->>API: POST /admin/impersonate/extend
    API->>DB: Refresh expiresAt (max 4h from creation)
    API->>API: Fetch latest session status
    API-->>UI: Updated expiresAt
    UI->>UI: Reset countdown timer
    UI->>UI: Show success toast
    
    Admin->>UI: Click "Exit Impersonation"
    UI->>API: DELETE /admin/impersonate
    API->>DB: Set endedAt + endReason='manual'
    API->>Events: Emit security.impersonation_ended
    Events->>DB: Log audit + notify target user
    API-->>UI: Confirmation
    UI->>UI: Clear localStorage + reload page
    UI->>UI: Return to normal admin view

Loading

sequenceDiagram
    participant Agent as Agent User
    participant UI as Frontend UI
    participant API as API Server
    participant DB as Database
    participant ContactOwner as Contact Owner
    participant Events as Event System

    Agent->>UI: View contact with basic access
    UI->>UI: Display "Limited View" badge
    UI->>UI: Show "Request Access" button
    
    Agent->>UI: Click "Request Access"
    UI->>API: POST /contacts/{id}/share-requests
    API->>DB: Check contact exists in agency
    API->>DB: Verify not already owned by requester
    API->>DB: Check no existing pending request
    API->>DB: Create contact_share_requests record<br/>(status='pending')
    API->>Events: Emit contact.share_requested
    Events->>DB: Create audit log
    API-->>UI: Share request created
    UI->>UI: Button → "Request Sent" (disabled)
    UI->>UI: Show success toast
    
    ContactOwner->>UI: View pending share requests
    UI->>API: GET /share-requests/pending
    API->>DB: Fetch pending requests for owner
    API-->>UI: List of pending requests
    
    ContactOwner->>UI: Click "Approve" request
    UI->>API: PATCH /share-requests/{id}
    API->>DB: Validate request pending status
    API->>DB: Update status='approved'
    API->>DB: Set resolvedAt + resolvedBy
    API->>API: Create ContactShare (full access)
    API->>Events: Emit contact.share_approved
    Events->>DB: Log audit event
    API-->>UI: Request approved
    UI->>UI: Show success notification
    
    Agent->>UI: Refresh contact view
    UI->>API: GET /contacts/{id}
    API->>DB: Check ContactShare record exists
    API->>API: Set _accessLevel='full'
    API-->>UI: Contact with full access
    UI->>UI: Display full contact details

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• PR #18: Modifies DashboardService.getStats signature and adds trip/contact filtering via access services; overlaps directly with dashboard controller/service changes in this PR for agent-scoped statistics.
• PR #19: Updates dashboard controller/service call sites for getStats and getDateRanges parameters; shares dashboard refactoring scope with this PR's access-control additions.

Poem

🐰 Hop, hop! The admin now impersonates with grace,
While agents request access to contacts at their pace,
Security logs every move with audit cheer,
And share requests bloom when access draws near!
RBAC fortified, the warren's secure! 🔐✨

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/rbac-hardening

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}