Dev

docs/changes/user-roles-change-log.csv

@@ -0,0 +1,7 @@
+Change ID,Date,Ticket,Branch,Commit,Area,Change Type,File Path,Class or Method,Previous Behaviour,New Behaviour,Reason,Database Impact,API Impact,Security Impact,Tests Added,Test Result,Developer Notes
+UR-001,2026-09-15,Not provided,feat/user-role-administration,Not committed,User lifecycle,Foundation,"fineract-provider/src/main/java/org/apache/fineract/nsimbi/userroles/domain/NsimbiUserSecurityProfile.java",NsimbiUserSecurityProfile,"No Nsimbi-specific suspension or successful-login record","Additive per-operator security profile stores suspension and successful last login","Keep operator lifecycle separate from Staff and client records","New nsimbi_user_security_profile table","No public API completed in this logical unit","Suspension is checked at authentication; failed authentication does not update last login","Not yet","Not run","Profile is created lazily so existing users keep their prior login behaviour until used."
+UR-002,2026-09-15,Not provided,feat/user-role-administration,Not committed,Monetary authority,Foundation,"fineract-provider/src/main/java/org/apache/fineract/nsimbi/userroles/service/NsimbiMonetaryAuthorityPolicyService.java",allows,"No Nsimbi monetary authority model","Defines ten authority types and an inclusive decimal/currency policy contract","Establish reusable future enforcement boundary without changing transactions","New nsimbi_user_monetary_authority table","No public API completed in this logical unit","No transaction handler is enrolled, avoiding unexpected lockout","Not yet","Not run","Zero/unset is represented as unconfigured and never treated as unlimited."
+UR-003,2026-09-15,Not provided,feat/user-role-administration,Not committed,Roles and branches,Migration,"fineract-provider/src/main/resources/db/changelog/tenant/parts/0242_nsimbi_user_roles_foundation.xml",Liquibase changesets,"No extension persistence","Adds branch-assignment and role-operating-hours tables plus required permission seeds","Create forward-compatible Nsimbi extension storage","Four additive tables and five permissions","No public API completed in this logical unit","Permissions are role-granted through existing Fineract RBAC","Not yet","Not run","Operating-hours schema records weekday windows; enforcement and holiday integration remain to be added."
+UR-004,2026-09-15,Not provided,feat/user-role-administration,Not committed,Code quality,Correction,"fineract-provider/src/main/java/org/apache/fineract/nsimbi/userroles","All new Java sources","New Java files used abbreviated licence comments and unvalidated monetary construction","Applies full Apache licence headers and validates user/type, uppercase ISO currency and inclusive monetary range ordering","Meet repository licensing and defensive-validation conventions","None","None","Invalid authority configurations fail before persistence","NsimbiUserMonetaryAuthorityTest","Passed: 2 tests; zero failures, errors, or skips; Gradle exit code 0 and BUILD SUCCESSFUL","Focused verification used existing compiled outputs where Gradle reported tasks up-to-date."
+UR-005,2026-09-15,Not provided,feat/user-role-administration,Not committed,Authentication and policy,Tests,"fineract-provider/src/test/java/org/apache/fineract","Focused unit tests","No tests covered the extension checkpoint","Adds suspension-checker, login-event delegation, fixed-clock last-login, inclusive authority and missing-authority policy tests","Establish focused regression coverage before expanding scope","None","None","Covers denial paths and success-event tracking boundary","PlatformUserDetailsCheckerTest; NsimbiUserSecurityServiceTest; NsimbiUserMonetaryAuthorityTest; NsimbiMonetaryAuthorityPolicyServiceTest; LoginAttemptEventListenerTest","Passed: 5 focused classes, 11 tests; zero failures, errors, or skips; Gradle exit code 0 and BUILD SUCCESSFUL","Focused verification used existing compiled outputs where Gradle reported tasks up-to-date; live database/Liquibase and Docker-dependent integration behaviour remain unverified."
+UR-006,2026-09-16,Not provided,feat/user-role-administration,Not committed,Verification,Environment,"/home/ib-s-muhoza/.gradle","Terminal Gradle verification","Focused execution could disappear before a terminal result","Stopped stale daemons and ran the focused suite with OpenJDK 25.0.4, Gradle 8.14.5, writable Gradle cache, and a command-only 4 GiB Gradle heap","Obtain a reliable focused result without global configuration changes","None","None","None","Five focused test classes","Passed: 11 tests; zero failures, errors, or skips; exit code 0 and BUILD SUCCESSFUL; git diff --check passed","Root cause of prior interruptions was host memory exhaustion from multiple Gradle daemons and VS Code processes, not a code failure. Database/Liquibase integration against a live test database and Docker-dependent integration behaviour remain unverified."

docs/changes/user-roles-implementation-report.md

@@ -0,0 +1,73 @@
+# Nsimbi SACCO Core Banking System — User and Roles implementation report
+
+## Status
+
+This is an in-progress Phase 1 foundation on `feat/user-role-administration`, based on local `develop` commit `9493c8b71f439db26dfa0006547ab1e0992ced4b`. No commit has been made. The supplied requirements comparison is now stored verbatim at `docs/requirements/user-roles-requirements-comparison.md`.
+
+## What is in this logical unit
+
+Fineract already has an application-user record (`m_appuser`), multiple roles (`m_role`), role permissions (`m_permission`), an optional Staff link, a primary Office, command auditing, password reset, login retry locking, notifications, tellers and cashiers. The Nsimbi work intentionally builds alongside these records instead of confusing an operator with a SACCO client/member.
+
+The migration creates additive Nsimbi tables: `nsimbi_user_security_profile`, `nsimbi_user_office_assignment`, `nsimbi_role_operating_hours`, and `nsimbi_user_monetary_authority`. It adds five Fineract RBAC permission codes: `SUSPEND_USER`, `REACTIVATE_USER`, `MANAGE_USER_BRANCH_ASSIGNMENTS`, `MANAGE_ROLE_OPERATING_HOURS`, and `MANAGE_USER_MONETARY_AUTHORITY`.
+
+`NsimbiUserSecurityProfile` records administrative suspension and a successful `lastLoginAt`. The existing `LoginAttemptEventListener` records the timestamp only from Spring Security's success event. `PlatformUserDetailsChecker` rejects a suspended operator before authentication completes. A failed attempt therefore cannot update the timestamp.
+
+`NsimbiMonetaryAuthorityPolicyService` provides a future transaction-handler boundary. It uses `BigDecimal`, explicit uppercase ISO currency, and inclusive comparisons. Its entity constructor rejects a minimum greater than a maximum. It returns false for an absent authority; this is deliberately not yet wired into banking transactions, so existing users are not locked out during migration.
+
+```mermaid
+flowchart LR
+  A[Operator login] --> B[Fineract authentication]
+  B --> C{Nsimbi suspended?}
+  C -- yes --> D[Reject authentication]
+  C -- no --> E[Authentication success event]
+  E --> F[Store lastLoginAt]
+  G[Future transaction handler] --> H[Nsimbi monetary policy]
+  H --> I[Configured inclusive range decision]
+```
+
+## Deferred decisions and limitations
+
+- Public management APIs, command handlers, authenticated-session invalidation, DTO extensions, role-hours validation/enforcement, branch-assignment validation/enforcement, and transaction-handler enforcement remain deferred. The tables are persisted only; they are not presented as complete features.
+- Role disablement currently cannot be applied while the role is assigned in core Fineract. That conflicts with the agreed rule and needs a targeted core change with regression coverage.
+- The teller model is office-scoped and references debit/credit GL accounts; a cashier is a Staff assignment valid for a period. Please decide whether the requirement's “Till” means a Fineract Teller, a Cashier assignment, a GL account, or a new SACCO till concept before behavioural enforcement is designed.
+- Notifications remain Fineract in-application notifications; product-specific License and Msacco event meanings are not invented here.
+
+## Requirements traceability
+
+| Requirement | Existing Fineract Capability | Nsimbi Extension | Implementation Status | Files | Tests | Deferred Reason |
+| --- | --- | --- | --- | --- | --- | --- |
+| Separate operator identity, optional Staff and primary Office | `m_appuser`, optional Staff, required Office | No separate contact record | Reused / Deferred | AppUser core model; Nsimbi tables | Existing Fineract tests | Phone/contact decision deferred |
+| Suspension/reactivation and readable status | Account enabled/locked plus login retry lock | Profile has `suspended`; authentication checker rejects it | Persisted and authentication-enforced; not API-authorized | Security profile, checker, listener | Focused tests passed | Commands/APIs and existing-session invalidation deferred |
+| Successful last login only | Authentication success/failure events | `lastLoginAt` updated only by success listener | Enforced at event boundary | LoginAttemptEventListener, security service | Focused tests passed | Persistence integration test deferred |
+| Multiple roles and disabled-role assignment behaviour | Many-to-many roles; core rejects disabling assigned role | None | Reused / Deferred | Fineract Role service | None added | Requires approval for smallest compatible core change |
+| Additional branch assignment | Primary Office only | Assignment table | Persisted only | 0242 migration | None | Validation, policy and API deferred |
+| Operating hours in Africa/Kampala | None | Clock bean and hours table | Persisted / timezone configured only | Clock config, 0242 migration | None | Validator, most-restrictive-role policy and boundaries deferred |
+| Ten monetary authority pairs | None | Ten enum values, authority table and inclusive policy | Persisted, validated in constructor, policy callable; not transaction-enforced | Monetary authority classes, 0242 migration | Focused tests passed | Management API and rollout activation deferred |
+| Notifications and preferences | In-application notifications | None | Deferred | Existing notification module | None | Event meanings and scope rules need product decisions |
+| Till and Chart Accounts | Teller has office and debit/credit GL accounts; Cashier links Staff to Teller | None | Deferred | Teller/cashier services | None | Teller, Cashier, GL and SACCO till are distinct concepts |
+
+## Verification
+
+`git diff --check` completed with no output and `xmllint --noout fineract-provider/src/main/resources/db/changelog/tenant/parts/0242_nsimbi_user_roles_foundation.xml` completed successfully. Focused tests cover administrative suspension, successful-login tracking with a fixed clock, failure-event non-tracking, inclusive authority boundaries, a missing authority, and an invalid range.
+
+The Gradle build declares a Java 25 toolchain. Terminal verification used OpenJDK 25.0.4 (Java and Javac) with Gradle 8.14.5 and a writable `/home/ib-s-muhoza/.gradle` cache. The focused commands used a command-only 4 GiB Gradle heap; no global configuration was changed.
+
+The focused suite was invoked as follows:
+
+```bash
+./gradlew :fineract-provider:test \
+  --tests org.apache.fineract.infrastructure.security.service.LoginAttemptEventListenerTest \
+  --tests org.apache.fineract.infrastructure.security.service.PlatformUserDetailsCheckerTest \
+  --tests org.apache.fineract.nsimbi.userroles.domain.NsimbiUserMonetaryAuthorityTest \
+  --tests org.apache.fineract.nsimbi.userroles.service.NsimbiMonetaryAuthorityPolicyServiceTest \
+  --tests org.apache.fineract.nsimbi.userroles.service.NsimbiUserSecurityServiceTest \
+  --no-daemon --console=plain --stacktrace --info
+```
+
+The focused suite completed with exit code `0` and `BUILD SUCCESSFUL`: all five focused test classes passed, executing 11 tests with zero failures, errors, or skips. Gradle reported the production and test compilation tasks as up-to-date, so this verification used existing compiled outputs where those tasks were not recompiled.
+
+The earlier build interruptions were caused by host memory exhaustion: multiple Gradle daemons and VS Code processes consumed excessive RAM. This was an environment failure, not a code failure. Database/Liquibase integration against a live test database and Docker-dependent integration behaviour remain unverified. All deferred module scope listed above remains deferred.
+
+## Licensing
+
+No Apache licence, NOTICE, copyright, or attribution files were removed or altered. New Java files must receive the repository's full Apache header before this work is ready for review.

docs/requirements/user-roles-requirements-comparison.md

@@ -0,0 +1,176 @@
+Continue the existing User and Roles Phase 1 implementation on branch `feat/user-role-administration`.
+
+Do not create another branch. Do not commit, push, merge or rebase.
+
+The current work is an acceptable intermediate checkpoint, but it is not ready for review or commitment.
+
+First perform these checks:
+
+1. Show `git status --short`.
+2. Show `git diff --stat`.
+3. List all untracked files.
+4. Confirm the exact paths of:
+
+   * the implementation report;
+   * the CSV change log;
+   * the database migration;
+   * every new Java file.
+5. Check whether the branch was created from the intended local `develop` commit.
+6. Fetch remote references and report whether local `develop` is behind, ahead of or diverged from `origin/develop`.
+7. Do not change the branch base without my approval.
+
+Requirements document:
+
+I will provide the previously generated requirements comparison separately.
+
+Save its exact content as:
+
+`docs/requirements/user-roles-requirements-comparison.md`
+
+Do not reconstruct or summarize missing requirements from memory. Once supplied, compare the implementation against every listed User and Roles field and add a traceability table to the implementation report with these columns:
+
+`Requirement | Existing Fineract Capability | Nsimbi Extension | Implementation Status | Files | Tests | Deferred Reason`
+
+Immediate correction:
+
+Add the repository-required full Apache licence header to every newly created Java source file. Do not alter existing licence, NOTICE, attribution or copyright files.
+
+Continue Phase 1 with the following priorities:
+
+1. Complete persistence mappings and database migration validation.
+2. Complete validation for:
+
+   * administrative suspension/reactivation;
+   * additional branch assignments;
+   * role operating hours;
+   * monetary authority ranges;
+   * ISO currency codes;
+   * minimum amount not exceeding maximum amount;
+   * duplicate records and assignments.
+3. Complete request and response DTOs.
+4. Add management service and command-handler operations.
+5. Add properly authorized REST API endpoints.
+6. Ensure every modifying operation uses Fineract’s command/audit conventions.
+7. Add unit and integration tests.
+8. Update the CSV and Markdown implementation report after each logical change.
+
+Suspension requirements:
+
+* A suspended user must be rejected during authentication.
+* Failed authentication must not update `lastLoginAt`.
+* Successful authentication must update `lastLoginAt`.
+* Suspension and reactivation must require their respective permissions.
+* Suspension must not delete roles, office assignments or monetary policies.
+* Determine how authentication sessions or tokens work in this Fineract revision.
+* Propose the safest compatible method for invalidating existing access after suspension.
+* If immediate session invalidation cannot be completed safely in this logical unit, document the exact technical limitation and ensure subsequent authenticated requests still reject the suspended user where possible.
+* Add tests covering all these cases.
+
+Branch-assignment requirements:
+
+* Primary office remains the existing required Fineract office.
+* Additional offices are explicit assignments.
+* Reject duplicate additional-office assignments.
+* Decide and document whether assigning the primary office again as an additional office is rejected or ignored.
+* Check tenant ownership and office existence.
+* Require `MANAGE_USER_BRANCH_ASSIGNMENTS` for management operations.
+* Do not yet modify every banking endpoint.
+* Provide a reusable authorization/policy service for future endpoints.
+* Test assigned and unassigned-office decisions.
+
+Role operating-hours requirements:
+
+* Use `Africa/Kampala` as the initial policy timezone.
+* Do not hard-code the server’s system timezone.
+* Validate opening and closing times.
+* Define behaviour for overnight time ranges instead of accidentally accepting them.
+* Make clock/time access injectable for deterministic tests.
+* Require `MANAGE_ROLE_OPERATING_HOURS`.
+* Add boundary tests for exactly opening time, exactly closing time, before opening and after closing.
+* Do not yet terminate existing sessions at closing time.
+
+Monetary-authority requirements:
+
+* Keep all ten required operation types.
+* Use `BigDecimal`.
+* Store an explicit ISO currency.
+* Comparisons are inclusive.
+* Reject a minimum greater than the maximum.
+* An absent or unset authority must not silently mean unlimited.
+* Existing users must not be locked out merely because the migration has run.
+* Keep actual transaction-handler enforcement deferred until we approve a backward-compatible rollout.
+* Add policy-service tests for:
+
+  * exact minimum;
+  * exact maximum;
+  * below minimum;
+  * above maximum;
+  * inside range;
+  * missing authority;
+  * wrong currency;
+  * invalid configuration.
+
+Role disablement:
+
+Do not change core Fineract’s assigned-role disablement guard yet.
+
+Instead:
+
+1. Analyze its security and compatibility consequences.
+2. Propose the smallest safe change.
+3. Identify required regression tests.
+4. Record it as a deferred decision requiring approval.
+
+Till and Chart Accounts:
+
+Keep these requirements in the traceability matrix but do not implement them yet. Do not assume Teller, Cashier, Till and GL Account are equivalent.
+
+Testing environment:
+
+The previous run found Java 21, while the repository instructions require Java 25.
+
+Before installing or modifying system Java:
+
+1. Inspect Gradle toolchain configuration.
+2. Inspect repository scripts, containers, devcontainers and CI workflows for the intended Java 25 setup.
+3. Check whether a compatible Java 25 installation already exists.
+4. Prefer the repository-supported environment.
+5. Use a writable project-specific Gradle cache if required.
+6. Do not alter global Java or Gradle configuration without approval.
+
+Run the narrowest relevant tests first. If Java 25 remains unavailable, still inspect and write the tests, but do not claim they pass.
+
+Documentation:
+
+Continue updating:
+
+* `docs/changes/user-roles-change-log.csv`
+* `docs/changes/user-roles-implementation-report.md`
+
+The report must remain understandable to someone learning Java. For each logical feature, explain the path from API request through validation, command/service, entity/repository and database.
+
+Do not claim a feature is complete merely because its data can be stored. Distinguish:
+
+* persisted;
+* validated;
+* exposed through API;
+* authorized;
+* enforced;
+* tested.
+
+At the end of this continuation, report:
+
+1. completed functionality;
+2. incomplete functionality;
+3. changed and untracked files;
+4. migrations;
+5. API endpoints;
+6. permission checks;
+7. exact tests executed and results;
+8. Java/Gradle environment status;
+9. requirements traceability status;
+10. risks and approval decisions;
+11. suggested next logical unit;
+12. confirmation that the CSV and Markdown reports are current.
+
+Do not commit until I explicitly approve it.