Skip to main content

Documentation Index

Fetch the complete documentation index at: https://grantmaster.dev/llms.txt

Use this file to discover all available pages before exploring further.

​
Security & Multi-Tenancy

StatusUpdatedCovered Files
🟢 Stable2026-03-14RBACContext.tsx, BaseService.ts, Firestore Rules, securityMonitoringService.ts, AuthContext.tsx

​
Multi-Tenancy Architecture

GrantMaster uses a Logical Isolation strategy for multi-tenancy. All customers share the same database collections, but every document is strictly tied to an organizationId.

​
Layers of Defense

  1. Frontend (Context): TenantProvider and RBACContext ensure the UI only shows data for the active organization.
  2. Service Layer (BaseService): Every write operation checks validateOrganizationId(orgId). This is a programmatic barrier against “ID Reference” attacks.
  3. Backend (Firestore Rules): Security rules enforce that request.auth.token.organizationId == resource.data.organizationId. Even if the code is bypassed, the database blocks the request.

​
Role-Based Access Control (RBAC)

​
System Roles

  • SUPER_ADMIN: Full access to all organizations, imuseration (impersonation) capabilities, and platform settings.
  • AUDITOR: Read-only access to specific organizations via temporary AuditorAccessGrant.
  • ADMIN: Manage organization settings, users, and billing.
  • MANAGER: Full access to grants and projects but no user/billing management.
  • MEMBER: Standard operational access (journals, expenses, activity).

​
Permission Enforcement

We use a Permission Matrix approach. Instead of checking roles (e.g., if (user.role === 'Admin')), we check capabilities: 
<PermissionGuard permission="APPROVE_EXPENSE">
  <ApprovalButton />
</PermissionGuard>

​
Advanced Security Features

  • Imuseration (Impersonation): SuperAdmins can switch contexts to another organization’s organizationId for support. This creates an ImuserationSession trackable in the audit logs.
  • Auditor Access: Auditors do not belong to an organization. Instead, they represent external regulatory bodies and are granted timed, scope-limited access to specific modules.

​
Security Monitoring Service (Added March 2026)

Source: src/shared/auth/securityMonitoringService.ts
A comprehensive security event logging and monitoring service integrated into the OAuth login flow via AuthContext.tsx.

​
Capabilities

  • Event Logging: logSecurityEvent() writes security events to Firestore with full metadata (IP, device, location).
  • Suspicious Login Detection: detectSuspiciousLogin() checks for location/device changes and rapid location changes between login attempts.
  • Concurrent Session Detection: detectConcurrentSessions() identifies active sessions from different IP addresses.
  • Account Locking: lockUserAccount() auto-locks accounts after configurable thresholds (default: 5+ security events), logs the event, and notifies admins.
  • Account Unlocking: unlockUserAccount() provides admin-controlled unlock with full audit trail.
  • Event Resolution: resolveSecurityEvent() allows admins to resolve flagged security events.
  • Alert Configuration: getSecurityAlertConfigs() and updateSecurityAlertConfig() for per-org threshold configuration.

​
Tracked Event Types

failed_login, suspicious_login, password_change, account_locked, account_unlocked

​
Integration with Auth Flow

AuthContext.performOAuthLogin() now calls:
  1. detectSuspiciousLogin() post-login to flag anomalous access patterns
  2. detectConcurrentSessions() to identify potential credential sharing
  3. logSecurityEvent() on both success and failure for audit completeness

​
Data Privacy & Compliance

  • PII Protection: User profile data is restricted. Only Admins can see full employee details within an organization.
  • Audit Logging: Every sensitive action (create, delete, status change) is captured in the systemEvents collection via the EventBus.
  • AI Safety Guards: responseSafety.ts checks all RAG responses for PII exposure before returning to users (see AI Engine docs).

​
Maintenance

Update this document when:
  • Adding a new SystemRole.
  • Modifying the multi-tenancy rules in firestore.rules.
  • Changing how PermissionGuard resolves its logic.

​
Update Checklist

  1. Reflect changes in src/shared/auth/contracts.ts.
  2. Update the permissionMatrix.ts in the code.