Documentation Index

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

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

​

Portal Security Model

Last updated: 2026-04-05

​

Overview

​

Key principles

• No user account required. Stakeholders never create credentials; access is entirely token-based.
• Least-privilege data exposure. Each token carries a visibility configuration that controls exactly which data categories the stakeholder can see or interact with.
• Audit-first design. Every portal session, page view, and action (comment, acknowledgment, upload) is recorded for compliance traceability.
• Organization-scoped isolation. A token is bound to a single organization and a single project. Cross-tenant access is impossible by construction.

​

Authentication Model

​

Token-based access (portal app)

1. An admin or manager in the main app creates a portal token via the CreateTokenModal UI.
2. PortalTokenService.createToken() generates a 64-hex-character token using the Web Crypto API (crypto.getRandomValues) and stores it in the portalTokens Firestore collection.
3. The admin shares the resulting URL (e.g., https://impact.grantmaster.ai/<tokenId>) with the stakeholder.
4. When the stakeholder opens the URL, the portal app extracts the tokenId from the route parameter and calls the validatePortalToken Cloud Function.
5. The Cloud Function validates the token (existence, active status, expiry, IP restrictions), creates an audit session, and returns filtered project data.
6. The portal stores the returned payload in sessionStorage and renders the dashboard.

​

Portal tokens in the tRPC/API layer

• type: 'portal'
• Two read-only permissions: VIEW_PROJECTS and VIEW_REPORTS
• isSuperAdmin: false
• portalProjectId scoping queries to the bound project

​

Portal Token Lifecycle

​

Generation

​

Fields on a PortalToken document

​

Validation checks (in order)

1. Existence — Token document must exist in Firestore. Returns not-found if missing.
2. Active status — isActive must be true. Returns permission-denied if revoked.
3. Expiry — expiresAt must be in the future. Returns permission-denied if expired.
4. IP restriction (in validatePortalToken handler) — If allowedIpAddresses is populated, the client IP must be in the list. Returns permission-denied otherwise.

​

Revocation

​

Expiry presets

​

Visibility Configuration

​

Firestore Security Rules

​

portalTokens/{tokenId}

​

portalSessions/{sessionId}

​

portalComments/{commentId}

​

portalReportAcknowledgments/{ackId}

​

portalSubmissions/{submissionId}

​

Design rationale: Cloud Function gatekeeping

• Token validation happens in trusted server-side code, not in client-side rule evaluation.
• Rate limiting, IP checks, and business logic (e.g., checking visibility.allowComments) are enforced before any data is written.
• Session tracking and notification events are created atomically alongside the primary write.

​

Data Access Boundaries

​

What portal users CAN see (when visibility allows)

• Project name, code, phase, description
• Budget utilization percentage and optionally amounts and line items
• Milestone/reporting deadline status and completion rates
• Timeline (start/end dates)
• Team member names and roles (no email addresses or internal IDs)
• Compliance health indicator (derived, not raw data)
• Impact metrics: SDGs, beneficiaries, outcomes, regions
• Generated reports list (name, type, date — no download of report files)
• Trend charts (budget burn, impact delivery, milestone completion)

​

What portal users CANNOT see

• Other projects in the organization
• Other organizations’ data (tenant isolation)
• Raw financial data (individual expenses, invoices, receipts)
• Employee personal details beyond name and role
• Internal notes, audit logs, or compliance details
• Grant application data or pipeline information
• User accounts, roles, or permissions
• System configuration or billing information
• Other stakeholders’ portal tokens

​

What portal users CAN do (when visibility allows)

• Post comments in a discussion thread
• Acknowledge reports (received, approved, request revision)
• Upload documents via signed URLs (PDF, DOCX, XLSX, DOC, XLS, JPEG, PNG; max 50 MB)

​

Cross-project isolation

​

Route Protection and Authorization

​

Portal app routing

1. PortalLanding calls validateToken() (Cloud Function). If validation fails, an error screen is shown (invalid, expired, revoked, or network error). If it succeeds, validated data is stored in sessionStorage and the user is redirected to the dashboard.
2. ProjectDashboard checks sessionStorage for the token’s data. If missing (direct navigation without validation), it redirects back to /:tokenId to force re-validation.

​

Session management

• A portalSessions document is created on each successful token validation, recording IP address, user agent, and timestamp.
• Page views and actions are appended to the session via updatePortalSession.
• When the portal component unmounts, endSession() is called to mark the session end time.
• Sessions provide a complete audit trail of what the stakeholder viewed and did.

​

CORS restrictions

const PORTAL_CORS = [
  'https://impact.grantmaster.ai',
  'https://grantmaster-portal.web.app',
  // Localhost only in emulator mode
  ...(process.env.FUNCTIONS_EMULATOR === 'true' ? ['http://localhost:3001'] : []),
];

​

Rate Limiting

​

File Upload Security

1. The portal calls getPortalUploadUrl with file metadata. The Cloud Function validates the token, checks allowReportSubmission visibility, validates MIME type and file size, then generates a time-limited (15-minute) signed URL for a specific storage path.
2. The portal uploads the file directly to Firebase Storage using the signed URL.
3. After upload, the portal calls submitPortalReport to create the portalSubmissions record linking the uploaded file.

• Allowed MIME types: PDF, DOCX, XLSX, DOC, XLS, JPEG, PNG
• Maximum file size: 50 MB
• Filenames are sanitized (path separators and special characters stripped, truncated to 200 chars)
• Storage path is namespaced: portal-submissions/{orgId}/{projectId}/{submissionId}/{filename}
• Signed URLs expire after 15 minutes

​

Notification Integration

​

Security Considerations and Best Practices

​

Token hygiene

• Rotate tokens periodically. Use the expiration presets to ensure tokens do not remain valid indefinitely. The recommended maximum is 1 year for ongoing funder relationships.
• Revoke promptly. When a stakeholder relationship ends or a project closes, revoke all associated tokens immediately.
• Use IP restrictions for high-sensitivity projects where the stakeholder’s network is known.
• Minimize visibility. Grant only the data categories the stakeholder needs. Use the “Funder Preset” as a starting point and remove unnecessary flags.

​

Transport security

• The portal is served over HTTPS only.
• Cloud Function CORS is restricted to known portal origins.
• Signed upload URLs use HTTPS and expire after 15 minutes.

​

Data leakage prevention

• Token IDs appear in URLs. Advise stakeholders to treat portal links as confidential.
• The portal stores validated data in sessionStorage (not localStorage), so it is cleared when the browser tab closes.
• No project data is cached on disk or persisted client-side beyond the browser session.

​

Monitoring

• Review portalSessions for unusual access patterns (high frequency, unexpected IPs, unusual user agents).
• Monitor portalTokens.accessCount to identify tokens that may have been shared beyond the intended stakeholder.
• Track unread stakeholder comments and pending submissions via the Grantors Portal tab in the main app.

​

Known limitations

• Rate limiting is in-memory per Cloud Function instance. Under high concurrency with many instances, the effective rate limit is per-instance, not global. For most portal workloads this is acceptable.
• Token IDs are opaque hex strings but are not hashed at rest in Firestore. Anyone with direct Firestore Admin access can read token values. This is mitigated by Firestore security rules preventing client-side reads by non-org-members.
• The portal app does not implement CSRF protection. This is acceptable because all mutations go through Firebase Cloud Functions (callable), which use their own CORS and authentication checks rather than cookie-based auth.