release: v3.3.24 – develop → staging

[nevil-mathew]

Summary by CodeRabbit

Release Notes

• New Features

  • Introduced Tenant Admin role with dedicated permissions and capabilities
  • Added role-based feature access controls

• Enhancements

  • Expanded role-based access control across admin operations
  • Improved tenant and organization-scoped operations

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

🗂️ Base branches to auto review (1)

• develop

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Walkthrough

Introduces tenant admin role capabilities and feature-role mapping infrastructure. Adds TENANT_ADMIN_ROLE constant, implements role assignment in admin services, creates database migrations for feature-role-mapping table and tenant admin setup, establishes new FeatureRoleMapping model with queries, expands role-based access controls across controllers, and updates authentication/service layers for tenant-organization scoped operations.

Changes

Cohort / File(s)	Summary
Core Constants & Localization src/constants/common.js, src/locales/en.json	Adds TENANT_ADMIN_ROLE constant definition (duplicated in exports); introduces new locale entries for tenant admin organization validation and role assignment (ORG_CODE_REQUIRED_FOR_TENANT_ADMIN, INVALID_ORG_CODE_FOR_TENANT, USER_ORGANIZATION_NOT_FOUND, USER_ROLE_ALREADY_EXISTS, INVALID_ROLE_ID, USER_ROLE_ASSIGNED_SUCCESSFULLY).
Admin Controller & Service src/controllers/v1/admin.js, src/services/admin.js	Adds assignRole method to admin controller with authorization checks; implements corresponding assignRole static method in AdminHelper to validate users, check organization associations, create role mappings with constraint error handling, and trigger post-assignment events/cache invalidation.
Authorization Expansions src/controllers/v1/notification.js, src/controllers/v1/org-admin.js, src/controllers/v1/organization.js	Expands role-based access checks to include TENANT_ADMIN_ROLE alongside ADMIN_ROLE and ORG_ADMIN_ROLE across multiple methods (create, update, details, addRegistrationCode, removeRegistrationCode).
Feature & Role Mapping Model src/database/models/featureRoleMapping.js, src/database/models/Feature.js, src/database/queries/featureRoleMapping.js	Introduces new FeatureRoleMapping model with id, role_title, feature_code, organization_code, tenant_code fields; establishes associations with Feature, Organization, and Tenant; adds query utilities (create, bulkCreate, findAll, delete).
Feature-Role Mapping Migrations src/database/migrations/20251002164809-*.js, src/database/migrations/20251002164938-*.js, src/database/migrations/20251002165109-*.js, src/database/migrations/20251003155747-*.js	Creates feature_role_mapping table with composite key; seeds 'scp' feature across tenants; populates feature-role mappings per organization/tenant; enforces foreign key constraints and unique partial index on (feature_code, role_title, organization_code, tenant_code).
Tenant Admin Role Initialization src/database/migrations/20251022160602-add-tenant-admin-role.js	Transactional migration that creates tenant_admin role records per tenant-organization combination, assigns copied admin-level permissions (excluding module 'admin' and specific permission IDs), with rollback support.
Service Layer Enhancements src/services/organization-feature.js, src/services/account.js	Adds transactional feature-role mapping creation/update in OrganizationFeatureHelper; extends list signature to accept userRoles for feature filtering by accessible roles; narrows role lookup by tenant_code in AccountHelper.
Feature Query & Access src/controllers/v1/organization-feature.js, src/database/queries/organization-feature.js	Passes user roles to feature list query; adds new findAllFeatureWithRoleMappings function to optionally join and filter by FeatureRoleMapping records based on role titles.
Authentication & Middleware src/middlewares/authenticator.js	Expands admin override logic to differentiate between isAdmin (with full header overrides) and isTenantAdmin (with tenant_code from token, orgCode validation via database lookup); adds error handling for missing orgCode and invalid tenant-organization combinations.
Notification Template Queries src/database/queries/notificationTemplate.js	Extends getEmailHeader and getEmailFooter signatures to accept tenantCode and organizationCode; applies tenant/organization filters during header/footer retrieval.
User Queries & Helpers src/database/queries/users.js, src/helpers/userInvite.js	Merges tenant_code into top-level where clause in listUsers; moves oldValues.organizations assignment before delta computation in userInvite helper; adjusts event emission to require newValues presence.
Configuration & Utilities src/package.json, src/envVariables.js, src/distributionColumns.sql	Adds "db:migrate" npm script; introduces databaseEnvironmentVariables object (pool and Postgres settings) merged into environment validation; applies cosmetic formatting to SQL distribution table calls.

Sequence Diagram(s)

sequenceDiagram
    participant Client
    participant AdminCtrl as Admin Controller
    participant AdminSvc as Admin Service
    participant UserQuery as User Queries
    participant OrgQuery as Organization Queries
    participant RoleQuery as Role Queries
    participant RoleMapQuery as Role-Mapping Queries
    participant EventBus as Event Bus
    participant Redis
    participant DB

    Client->>AdminCtrl: assignRole(req)
    AdminCtrl->>AdminCtrl: Validate ADMIN_ROLE
    AdminCtrl->>AdminSvc: assignRole(params, body)
    
    rect rgb(200, 220, 240)
        Note over AdminSvc: Validation Phase
        AdminSvc->>UserQuery: Find user by id
        UserQuery->>DB: Query user record
        DB-->>UserQuery: User found
        UserQuery-->>AdminSvc: User data
        AdminSvc->>OrgQuery: Verify org association
        OrgQuery->>DB: Query user.organizations
        DB-->>OrgQuery: Org list
        OrgQuery-->>AdminSvc: Org verified
        AdminSvc->>RoleQuery: Check role exists
        RoleQuery->>DB: Query role
        DB-->>RoleQuery: Role found/not found
    end

    rect rgb(220, 240, 200)
        Note over AdminSvc: Creation Phase
        AdminSvc->>RoleMapQuery: Create role mapping
        RoleMapQuery->>DB: Insert user_role record
        DB-->>RoleMapQuery: Mapping created (or constraint error)
    end

    rect rgb(240, 220, 200)
        Note over AdminSvc: Post-Assignment Cleanup
        AdminSvc->>UserQuery: Fetch updated user
        AdminSvc->>EventBus: Broadcast user update event
        EventBus-->>AdminSvc: Event sent
        AdminSvc->>Redis: Clear user cache
        Redis-->>AdminSvc: Cache cleared
        AdminSvc->>DB: End user sessions for tenant
        DB-->>AdminSvc: Sessions ended
    end

    AdminSvc-->>AdminCtrl: Success response
    AdminCtrl-->>Client: HTTP response

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Areas requiring extra attention:

• src/middlewares/authenticator.js: Significant logic refactor for tenant admin override handling; tenant_code/organization_code derivation logic differs from admin path and requires careful validation of all access control branches.
• src/database/migrations/20251022160602-add-tenant-admin-role.js: Complex transactional migration with role/permission seeding; verify transaction isolation, rollback paths, and permission exclusion logic (module='admin', IDs 35 and 40).
• src/database/migrations/20251002165109-map-roles-to-features.js: High-complexity seeding logic with deduplication, feature filtering, and skipped mapping tracking; validate role-feature assignment correctness and organizational scoping.
• src/services/organization-feature.js: Transactional create/update with nested role validation and feature-role-mapping; verify atomicity, role filtering in list method, and handling of empty role sets for non-admin users.
• Role-based access control changes across controllers (org-admin.js, organization.js, notification.js): Multiple similar but distinct additions of TENANT_ADMIN_ROLE checks; ensure consistent logic and no regression in authorization flow.

Possibly related PRs

• add(role): migration to create tenant_admin role and assign permissions #851: Directly related — introduces the identical TENANT_ADMIN_ROLE constant and tenant-admin migration, plus matching admin controller/service/locale/middleware changes.
• update: admin decode token flow #847: Modifies authenticator.js admin override logic with overlapping tenant-admin header validation and organization code handling.
• feat: implement feature-role mapping #836: Adds feature-role mapping surface (migrations, model, queries, organization-feature service list signature) across both PRs.

Poem

A tenant admin hops in sight, 🐇
With roles now mapped to features bright,
Migrations seed the role domain,
While auth flows verify with care and pain,
Feature access scoped per org—what delight!

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch develop

---

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.}

[nevil-mathew]

@coderabbitai summary

[coderabbitai]

✅ Actions performed

Summary regeneration triggered.