[ Backend ] - Checks, Roles and Action Controls

[jpaulet]

To ensure the organization can perform the desired action, the backend should implement the following checks and controls. These checks can be categorized into basic eligibility, feature-specific, and quota-related validations:

1. Subscription and Plan Validations

Subscription Status:

• Verify the organization has an active subscription.
• Check if the subscription is not expired (compare the current date with the endDate in the subscription record).

Plan-Specific Features:

• Confirm the requested action is allowed under the organization's subscription plan.For example, if the plan allows ranked-choice voting or custom branding, ensure the requested feature matches the allowed capabilities.

Quota Limitations:

• Verify that the organization has not exceeded any applicable quotas:
• Maximum census size: Check the number of voters in the draft or election against the limit for the subscription plan.
• Number of ongoing elections: Ensure the organization has not exceeded the allowed number of active elections under their plan.
• Monthly/annual limits: Track actions such as the number of elections created or notifications sent, ensuring these are within the plan's allowance.

Add-On Features:

• If certain features are pay-per-use or require separate purchase (e.g., advanced reporting, SMS notifications), confirm the feature is enabled or the organization has sufficient credits.

2. Role-Based Access Control (RBAC)

Admin Permissions:

• Verify the requesting user has the necessary role (e.g., "Admin" or "Election Manager") to perform the action.
• Check if the role explicitly grants access to manage specific resources (e.g., create/delete elections, manage census, change organization settings).

Scoped Permissions:

• For organizations with sub-organizations, confirm the admin has permissions for the specific sub-organization they are managing.
• Enforce separation of concerns by limiting access to only the resources within their scope.

3. Resource Ownership and Availability

Organization Ownership:

• Validate that the resource being managed (e.g., draft, election, census) belongs to the requesting organization.

---

Roles:

Feature/Action	Guest	Manager	Admin
Create process	❌	✅	✅
Create draft	❌	✅	✅
Edit organization	❌	❌	✅
Invite members	❌	❌	✅
Delete members	❌	❌	✅
Create suborganization	❌	❌	✅
Manage elections (play/pause)	❌	✅	✅
Cancel elections	❌	❌	✅
View election list & detail	✅	✅	✅
Manage subscriptions	❌	❌	✅

---

Checks

• isOrganizationMember(user, organization): check if action is performed by a member of that organization
• hasRolePermission(user, action): check if the action is perfomed by a user with the appropiate role in that organization
• isSubscriptionActive(organization): check if the current org has a active subscription
• isCensusWithinLimit(censusSize): check if the submited census size is valid for the current subscripton & tier
• isQuotaWithinLimit(quotaType, currentUsage): check if the current quota limit is less or equal than the plan limit. Possible quota limits:
  • nº of members (members)
  • nº of annual voting processes (processes)
  • nº of sub-orgs (subOrgs)
  • nº of drafts (drafts)
  • nº of emails (email)
  • nº of sms (sms)
• isFeatureEnabled(feature, plan): check if the current plan allows enabling the specific feature.
• isVotingTypeAllowed(votingType, plan): check if the current plan allows the specific voting type.

---

Checks for Actions

Create Process:

• Active subscription
• Is Organization Member
• Has Role Permission
• Allowed voting types
• Census size limit
• Quota limit for processes
• Check each feature enabled in the new process

Create Draft:

• Active subscription.
• Is Organization Member
• Has Role Permission
• Quota limit for drafts
• Feature permissions (drafts)

Edit Organization

• Active subscription
• Is Organization Member
• Has Role Permission

Invite Member:

• Active subscription
• Is Organization Member
• Has Role Permission
• Quota limit for members

Delete Member

• Active subscription
• Is Organization Member
• Has Role Permission

Create Sub-organization

• Active subscription
• Is Organization Member
• Has Role Permission
• Quota limit for subOrgs

Manage Elections (play/pause/cancel):

• Is Organization Member
• Has Role Permission

[jpaulet]

Priority

1. Create Process
2. Invite Member
3. Manage Elections

After completing these, we can decide whether to proceed with:

1. Delete Member
2. Create Draft
3. Create Sub-organization

---

Explanation of "Create Process" Feature Validation

When submitting a voting process, it will include a features[] object that lists each enabled feature with its corresponding key, something like this:

{
  ...
  "features": {
    "customization": {
      "color": "#fff",
      "logo": "https://...",
      "header": "https://...",
      "secondaryColor": "#000",
      ...
    },
    "streaming": "https://...",
    "redirectUrl": "https://..."
  }
}

In the above example, the backend must verify that the current subscription plan allows the use of the "customization", "streaming" and "redirectUrl" in the features list (all set to "true" in the Stripe metadata). If all features are allowed: The validation continues. If any feature is not allowed: The backend should return an array of the unsupported features.

This validation ensures we only store voting processes with the features available in their current subscription plan.