diff --git a/agent-memory/domains/authentication/issues/10004-feat9983-appurl-is-required-when-token-login-is-enabled.md b/agent-memory/domains/authentication/issues/10004-feat9983-appurl-is-required-when-token-login-is-enabled.md
new file mode 100644
index 00000000..35426e70
--- /dev/null
+++ b/agent-memory/domains/authentication/issues/10004-feat9983-appurl-is-required-when-token-login-is-enabled.md
@@ -0,0 +1,107 @@
+---
+id: cht-core-9983
+category: improvement
+domain: authentication
+domainFit: strong
+issueNumber: 9983
+issueUrl: https://github.com/medic/cht-core/issues/9983
+title: Require app_url config when token login (or OIDC) is enabled and read it from config instead of the request
+lastUpdated: '2026-09-29'
+summary: Token login and the OIDC login endpoints previously fell back to deriving the app URL from the incoming request when app_url was unset, and the api threaded that value as an appUrl parameter through the user-management functions. The PR removes the fallback and the parameter; token login and the OIDC handlers now read app_url from configuration and throw when it is missing, a breaking change that shipped in 5.0.0.
+services:
+  - api
+  - sentinel
+techStack:
+  - javascript
+  - nodejs
+  - mocha
+tags:
+  - token-login
+  - oidc
+  - app_url
+  - breaking-change
+  - user-management
+  - refactor
+related_workflows:
+  - user-registration
+source_pr: medic/cht-core#10004
+source_sha: 1dfd7e60df7c156da0fd20c4c5da80443d007a28
+distilled_at: '2026-06-22'
+reviewed_by: null
+reviewed_at: null
+confidence: medium
+entities:
+  - shared-libs/user-management/src/token-login.js
+  - shared-libs/user-management/src/users.js
+  - api/src/controllers/login.js
+  - api/src/controllers/users.js
+  - api/src/server-utils.js
+  - shared-libs/transitions/src/transitions/create_user_for_contacts.js
+concepts:
+  - token-based passwordless login
+  - OIDC authentication
+  - fail-fast on missing app_url
+  - single source of truth for app_url
+  - breaking API/config change
+related_issues:
+  - cht-core-9735
+stale: false
+---
+
+## Problem
+
+Enabling token login did not require the app_url setting to be configured. Before this PR, `getAppUrl` in api/src/server-utils.js (called as `serverUtils.getAppUrl(req)` from api/src/controllers/login.js) returned `config.get('app_url')` or, when that was unset, `${req.protocol}://${req.get('host')}`, which misses a non-standard port when the API runs in Docker behind a reverse proxy. api/src/controllers/users.js and api/src/controllers/login.js passed the result as an `appUrl` argument into the user-management `createUser`/`createUsers`/`createMultiFacilityUser`/`updateUser` functions, which handed it down through `manageTokenLogin` and `enableTokenLogin` to `generateTokenLoginDoc`, where the token-login SMS link is built. The create_user_for_contacts transition passed `config.get('app_url')` into the same `createUser` parameter, and the OIDC handlers in api/src/controllers/login.js built their callback URLs from the same helper.
+
+## Root Cause
+
+token-login methods accepted an appUrl argument that could be reconstructed from the request when app_url was not set in configuration, so the URL had multiple possible sources and had to be threaded through the login/user-creation call chain along with request-based fallback logic in server-utils.
+
+## Solution
+
+Removed `getAppUrl` from api/src/server-utils.js and dropped the `appUrl` parameter from `createUser`, `createUsers`, `createMultiFacilityUser` and `updateUser` (shared-libs/user-management/src/users.js) and from `manageTokenLogin`, `enableTokenLogin` and `generateTokenLoginDoc` (shared-libs/user-management/src/token-login.js). The api controllers, `updatePassword()` in api/src/controllers/login.js and the create_user_for_contacts transition stopped passing it. `generateTokenLoginDoc()` now reads `config.get('app_url')` itself and throws `app_url configuration is required for token login` when it is unset. In api/src/controllers/login.js a module-local `getAppUrl()` reads `config.get('app_url')`, throws `The app_url value is not configured.` when it is empty, and strips trailing slashes. `oidcLogin` and `oidcAuthorize` now build their URLs from it inside their try blocks, so without app_url `oidcLogin` redirects to the login page with `sso_error=loginerror` and `oidcAuthorize` responds through `serverUtils.error`. There is no settings-level validation. The token-login check fires only when token login is being enabled for a user, and by then `createUser`/`updateUser` have already saved the user and user-settings docs. The PR also split the bulk `createUsers` loop into `filterIgnoredUsers()` and `createSingleUser()` helpers. The change is marked breaking (`feat(#9983)!`) and shipped in 5.0.0. It is on the 5.x release branches only, not on any 4.x branch.
+
+## Code Patterns
+
+Read app_url from configuration at the point of use, as a single source of truth, rather than passing it as a parameter or deriving it from the request. Fail fast with an explicit error when it is missing: see `generateTokenLoginDoc()` in shared-libs/user-management/src/token-login.js and `getAppUrl()` in api/src/controllers/login.js. Because the check runs at the point of use rather than when settings are saved, callers that write docs first (`createUser`, `updateUser` in shared-libs/user-management/src/users.js) can fail after those writes.
+
+## Design Choices
+
+Chose to require app_url and source it from config rather than continue the request-based fallback, giving a single source of truth, simpler call signatures, and consistent handling for both token login and OIDC. It also matches the create_user_for_contacts transition, which already refused to run without app_url. Accepted that this is a breaking change and deferred merge to the 5.0.0 major release rather than preserving backward-compatible fallback.
+
+## Related Files
+
+- shared-libs/user-management/src/token-login.js
+- shared-libs/user-management/src/users.js
+- api/src/controllers/login.js
+- api/src/controllers/users.js
+- api/src/server-utils.js
+- shared-libs/transitions/src/transitions/create_user_for_contacts.js
+- shared-libs/user-management/test/unit/token-login.spec.js
+- shared-libs/user-management/test/unit/users.spec.js
+- api/tests/mocha/controllers/login.spec.js
+- api/tests/mocha/controllers/users.spec.js
+- api/tests/mocha/server-utils.spec.js
+- shared-libs/transitions/test/unit/transitions/create_user_for_contacts.js
+- tests/integration/api/controllers/login.spec.js
+
+## Testing
+
+- shared-libs/user-management/test/unit/token-login.spec.js and shared-libs/user-management/test/unit/users.spec.js drop the `appUrl` argument and stub `config.get('app_url')`.
+- api/tests/mocha/controllers/users.spec.js no longer stubs `serverUtils.getAppUrl`.
+- api/tests/mocha/controllers/login.spec.js reworks the existing error-path tests of `oidcLogin` and `oidcAuthorize` to use an empty app_url and assert the `The app_url value is not configured.` error.
+- api/tests/mocha/server-utils.spec.js deletes the `getAppUrl` tests.
+- The create_user_for_contacts transition test no longer expects an app_url argument.
+- The integration test tests/integration/api/controllers/login.spec.js now configures app_url by default (`setupTokenLoginSettings = (configureAppUrl = true, configureOidc = false)`) and adds it to the OIDC settings.
+
+This PR adds no test for the token-login throw. The one on master was added later by PR #10701.
+
+## Related Issues
+
+- #9983: "Require `app_url` to be set when enabling `token_login`" — this draft's issue (labelled Breaking change, milestone 5.0.0)
+- #9735: "Single sign on (SSO) using identity provider" — the SSO epic whose `oidcLogin`/`oidcAuthorize` handlers (landed via PR #9955) this PR made depend on a configured app_url
+
+## Domain Rationale
+
+**Fit:** strong
+
+Token login and OIDC are authentication mechanisms; this PR governs how those login flows can be enabled and how the login URL is sourced. Although app_url is an app-setting value, the subject matter is the authentication feature itself, not general configuration, so it is a strong fit for authentication rather than configuration.
diff --git a/agent-memory/domains/authentication/issues/10153-fix10062-address-race-condition-in-user-edit-model-for-sso.md b/agent-memory/domains/authentication/issues/10153-fix10062-address-race-condition-in-user-edit-model-for-sso.md
new file mode 100644
index 00000000..ffb4e4ea
--- /dev/null
+++ b/agent-memory/domains/authentication/issues/10153-fix10062-address-race-condition-in-user-edit-model-for-sso.md
@@ -0,0 +1,90 @@
+---
+id: cht-core-10062
+category: bug
+domain: authentication
+domainFit: strong
+issueNumber: 10062
+issueUrl: https://github.com/medic/cht-core/issues/10062
+title: Fix race condition in admin user edit modal that broke Facility and Associated contact field population for SSO users
+lastUpdated: '2026-10-05'
+summary: 'The admin app''s edit user modal intermittently left the Place (`facilitySelect`) and Associated contact (`contactSelect`) selects unpopulated, reproducibly for SSO users. The Select2 setup for both ran on `$uibModalInstance.rendered` without waiting for `determineEditUserModel()`, which for SSO users also waits on an extra `GET /api/v2/users/<name>`; the fix moves that setup into `populateFacilitynContact()`, called only after `$scope.editUserModel` is assigned.'
+services:
+  - admin
+techStack:
+  - javascript
+  - angularjs
+  - webdriverio
+tags:
+  - sso
+  - user-management
+  - race-condition
+  - edit-user-modal
+  - admin-app
+  - facility
+  - associated-contact
+  - select2
+related_workflows:
+  - user-registration
+source_pr: medic/cht-core#10153
+source_sha: cc8758d1dbb3665a933b55a921d5d24e075e2a75
+distilled_at: '2026-06-22'
+reviewed_by: null
+reviewed_at: null
+confidence: medium
+entities:
+  - admin/src/js/controllers/edit-user.js
+concepts:
+  - race condition
+  - asynchronous data loading
+  - modal form model population
+  - SSO user management
+  - data binding ordering
+related_issues:
+  - cht-core-9735
+  - cht-core-9761
+stale: false
+---
+
+## Problem
+
+When the edit user modal was opened in the admin app, the Place (label key `Facility`) and Associated contact selects were sometimes left empty or uninitialised. It was intermittent — the issue's repro is to give a user an SSO Email Address, then close and reopen their edit modal until it happens — and was reported from the community forum for SSO-enabled users; the issue is labelled as affecting 4.20.0 and 4.21.0.
+
+## Root Cause
+
+A race in admin/src/js/controllers/edit-user.js. `this.setupPromise = determineEditUserModel().then(model => { $scope.editUserModel = model; ... })` and a separate `$uibModalInstance.rendered.then(() => ContactTypes.getAll()).then(...)` chain ran independently. The second chain initialised both Select2 widgets from the model: the contact select via `Select2Search`, which takes its initial value from the `<option ng-value="editUserModel.contactSelect">` in the template, and the place select with `usersPlaces($scope.editUserModel.facilitySelect)`. If the modal rendered before the model had been assigned, the contact widget came up empty and reading `facilitySelect` off the still-undefined `$scope.editUserModel` threw, leaving the place widget uninitialised.
+
+The race was latent: the `rendered` chain dates from the admin app's creation and has read `$scope.editUserModel.facilitySelect` since PR #9128 (multiple places per user). What made it reproducible for SSO users is PR #9900, part of the SSO epic that reached master as PR #9955: `determineEditUserModel` now waits on `$q.all([Settings(), getOidcUsername()])`, and `getOidcUsername()` issues an extra `GET /api/v2/users/<name>` for users whose user-settings doc has `oidc_login`, so the model resolves later for exactly those users.
+
+## Solution
+
+Wrapped the `rendered` chain in a new `populateFacilitynContact()` (the name as spelled in the source) and called it from `setupPromise`'s `.then`, right after `$scope.editUserModel = model` and `validateSkipPasswordPermission()`. The contact select's `Select2Search` call also moved inside the `usersPlaces(...)` callback, so both widgets are initialised together, after the model exists and the place ids have been resolved. The fix was cherry-picked to 4.20.x (`7197a46c1`, first released in 4.20.1) and 4.21.x (`f02285311`, 4.21.1); on master it is first in 4.22.0. The same code is on master today, where `setupPromise` waits on `$q.all([determineEditUserModel(), datasourcePromise])` (added by PR #10795) before calling it.
+
+## Code Patterns
+
+Do not run view-widget initialisation off a render promise that races the model; chain it after the model promise instead. In admin/src/js/controllers/edit-user.js the `$uibModalInstance.rendered` → `ContactTypes.getAll()` → `Select2Search` sequence is started from inside `setupPromise`'s `.then`, after `$scope.editUserModel` is set, so it still waits for the modal to render but can no longer run before the model exists.
+
+## Design Choices
+
+The fix orders the widget setup after the model rather than masking the symptom in the view, so the modal behaves the same whichever of the model lookups and the render finishes first. No unit spec was changed; coverage is an e2e case, and rather than adding a new spec file the PR consolidated the add-user spec into one covering both creating and editing users.
+
+## Related Files
+
+- admin/src/js/controllers/edit-user.js
+- tests/e2e/default/users/user.wdio-spec.js (renamed by this PR from tests/e2e/default/users/add-user.wdio-spec.js)
+- tests/page-objects/default/users/user.wdio.page.js
+
+## Testing
+
+tests/e2e/default/users/add-user.wdio-spec.js was renamed to tests/e2e/default/users/user.wdio-spec.js (77% similar), with its fixtures hoisted to module scope. It gains one case, 'Editing User -> should render user details', which, with an `oidc_provider` configured, creates an offline (`chw`) user with a place, a contact and an `oidc_username`, opens the edit modal and asserts the username, role, place (`#facilitySelect`), contact (`#contactSelect`) and SSO email (`#sso-login`) values. The users page object (tests/page-objects/default/users/user.wdio.page.js) gains `openEditUserDialog` and `editUserDialogDetails`, plus the `getUsernameRow` and `userList` helpers they use.
+
+## Related Issues
+
+- #10062: "Rendering issue in edit user modal for SSO user" — this draft's issue.
+- #9761: "Update user creation frontend to support creating SSO users" — its PR #9900 added the `getOidcUsername()` request whose delay exposed this race.
+- #9735: "Single sign on (SSO) using identity provider" — the SSO epic that carried PR #9900 to master.
+
+## Domain Rationale
+
+**Fit:** strong
+
+The fix is in the admin app's user-account editor (`EditUserCtrl`), which configures a user's roles, place, contact and login method, and the regression it repairs was made reproducible by the SSO epic's `getOidcUsername()` lookup. User-account management and SSO are authentication concerns; the Place and Associated contact fields here are the user account's assignments, not contact records being edited.
diff --git a/agent-memory/domains/authentication/issues/10414-fix6784-safari-unsupported-browser-message-in-login-page.md b/agent-memory/domains/authentication/issues/10414-fix6784-safari-unsupported-browser-message-in-login-page.md
new file mode 100644
index 00000000..b869b0c7
--- /dev/null
+++ b/agent-memory/domains/authentication/issues/10414-fix6784-safari-unsupported-browser-message-in-login-page.md
@@ -0,0 +1,94 @@
+---
+id: cht-core-6784
+category: feature
+domain: authentication
+domainFit: strong
+issueNumber: 6784
+issueUrl: https://github.com/medic/cht-core/issues/6784
+title: Show an unsupported-browser message and hide the login fields for Safari users on the login page
+lastUpdated: '2026-09-29'
+summary: 'Safari users could log in from the CHT login page with no warning that Safari is unsupported. The PR adds client-side user-agent Safari detection to the login page script, which shows a localized "Safari is not supported. Please use Chrome or Firefox." message and hides the login form fields. Token (magic-link) login was not covered and was left to a follow-up issue.'
+services:
+  - api
+techStack:
+  - javascript
+  - html
+  - express
+  - i18n
+tags:
+  - safari
+  - browser-detection
+  - login
+  - unsupported-browser
+  - i18n
+  - user-agent
+  - token-login
+related_workflows: []
+source_pr: medic/cht-core#10414
+source_sha: 043e35d9992f0044ef5d9cbe232015e75f880def
+distilled_at: '2026-06-22'
+reviewed_by: null
+reviewed_at: null
+confidence: medium
+entities:
+  - api/src/controllers/login.js
+  - api/src/public/login/script.js
+  - api/src/templates/login/index.html
+  - api/resources/translations/messages-en.properties
+concepts:
+  - browser detection
+  - internationalization
+  - server-rendered login page
+  - token (magic link) login
+  - unsupported browser handling
+related_issues:
+  - cht-core-10494
+stale: false
+---
+
+## Problem
+
+Safari users could log in from the login page with no warning that Safari is unsupported by the CHT app, and then hit subtle, non-obvious breakage with no explanation (issue #6784). The expected message was: 'For a better app experience, please contact your administrator or supervisor. Safari is not supported. Please use Chrome or Firefox.'
+
+## Root Cause
+
+`checkUnsupportedBrowser()` in api/src/public/login/script.js had no Safari case. Outside cht-android, its only check was bowser's `parser.satisfies()` with `chrome: '>=90'` and `firefox: '>=98'`. That call returns `undefined` for a browser it does not list, so at most Safari got the generic `login.unsupported_browser.outdated_browser` text ("Let them know to update your browser."), and nothing hid the login form. Separately, the `DOMContentLoaded` handler called `ssoLoginButton.addEventListener('click', requestSSOLogin, false)` without a null check. The `id="login-sso"` button is rendered only `if(hasOidcProvider)` in api/src/templates/login/index.html and not at all in api/src/templates/login/token-login.html, so on the login page without an OIDC provider, and always on the token-login page, the handler threw before it reached `checkUnsupportedBrowser()`.
+
+## Solution
+
+The PR added `isSafariBrowser()` to api/src/public/login/script.js. It tests `navigator.userAgent` against `/^((?!chrome|android|crios|fxios).)*safari/i`, which skips user agents where `chrome`, `android`, `crios` or `fxios` appears before `safari`. For non-cht-android browsers, `checkUnsupportedBrowser()` tests it before the bowser version check and selects the new `login.unsupported_browser.safari` key. On Safari it also adds `hidden` to a new `id="login-fields"` wrapper in api/src/templates/login/index.html, which holds the username and password inputs, the error messages, and the login and SSO buttons, so the form cannot be used. api/src/controllers/login.js adds the key to the login template's `translationStrings`. The string was added to six of the nine bundled locale files: ar, en, es, fr, ne and sw, but not bm, hi or id. The PR also null-guards the `getElementById('login-sso')` listener and the `getElementById('user')` lookup, moving the page wiring into `handleLoginButton()`, `handleUserInputFocus()`, `handlePasswordInputFocus()`, `handlePasswordToggle()` and `handleServiceWorker()`. It also makes `isUsingSupportedBrowser()` return `false` instead of throwing when bowser is not loaded.
+
+## Code Patterns
+
+Client-side user-agent detection (`isSafariBrowser()` in api/src/public/login/script.js) feeds the existing `checkUnsupportedBrowser()`. That function writes the translated text into the `id="unsupported-browser-update"` span, un-hides the `id="unsupported-browser"` paragraph, and on Safari hides the `id="login-fields"` wrapper, all three in api/src/templates/login/index.html. A translation key reaches a login page only if it is listed in that template's `translationStrings` in api/src/controllers/login.js (`getTranslationsString()` encodes just those keys). A new message therefore needs an entry there as well as in api/resources/translations/messages-*.properties.
+
+## Design Choices
+
+On Safari the login form is hidden, not just accompanied by a warning. The issue asked for an alert at minimum and preferably for blocking Safari logins. The hiding is client-side only, and the API performs no browser check. In the `DOMContentLoaded` handler, `checkUnsupportedBrowser()` still runs after `requestTokenLogin()` has fired, so a token (magic-link) login still went through on Safari. That gap was left to a follow-up (#10494, PR #10502). The Safari detection lives inside the existing `checkUnsupportedBrowser()` rather than in a separate check, so all unsupported-browser handling stays in one function. The new string covers six of the nine bundled locales (not bm, hi or id).
+
+## Related Files
+
+- api/resources/translations/messages-ar.properties
+- api/resources/translations/messages-en.properties
+- api/resources/translations/messages-es.properties
+- api/resources/translations/messages-fr.properties
+- api/resources/translations/messages-ne.properties
+- api/resources/translations/messages-sw.properties
+- api/src/controllers/login.js
+- api/src/public/login/script.js
+- api/src/templates/login/index.html
+
+## Testing
+
+No tests were added or changed. The diff touches only the six translation files, api/src/controllers/login.js, api/src/public/login/script.js and api/src/templates/login/index.html.
+
+## Related Issues
+
+- #6784: "Alert Safari users CHT doesn't support their browser" — this draft's issue, which asks for an alert at minimum and preferably for blocking Safari logins
+- #10494: "Prevent logging in with token in Safari Browser" — the follow-up (PR #10502) that closed the token-login gap left open here
+
+## Domain Rationale
+
+**Fit:** strong
+
+The PR decides whether a Safari user can log in at all: on Safari it hides the login form and shows an unsupported-browser warning, as #6784 asked (an alert at minimum, preferably blocking Safari logins). That is login-flow policy, which is authentication. Enforcement is client-side only: it changes no credential, session or token handling, and the API still accepts logins from Safari. The six translation files carry the new string and do not register locales, so this is not configuration.
diff --git a/agent-memory/domains/authentication/issues/10502-feat10494-block-tokenlogin-for-safari.md b/agent-memory/domains/authentication/issues/10502-feat10494-block-tokenlogin-for-safari.md
new file mode 100644
index 00000000..90b441d4
--- /dev/null
+++ b/agent-memory/domains/authentication/issues/10502-feat10494-block-tokenlogin-for-safari.md
@@ -0,0 +1,89 @@
+---
+id: cht-core-10494
+category: improvement
+domain: authentication
+domainFit: strong
+issueNumber: 10494
+issueUrl: https://github.com/medic/cht-core/issues/10494
+title: Block token_login links for Safari users and show an unsupported-browser message
+lastUpdated: '2026-10-05'
+summary: 'Token login links opened in Safari still authenticated successfully even though regular login fields are already hidden for Safari users (from #6784). This extends the Safari block to the token_login page. The login script now runs the browser check first and does not send the token-login request from Safari, and the page renders a matching unsupported-browser message. The block is client-side only.'
+services:
+  - api
+techStack:
+  - javascript
+  - nodejs
+  - html
+tags:
+  - safari
+  - token-login
+  - browser-detection
+  - user-agent
+  - login
+  - unsupported-browser
+related_workflows:
+  - user-registration
+source_pr: medic/cht-core#10502
+source_sha: 03ec621fedb34c6f47bb35517492c35266632c1c
+distilled_at: '2026-06-22'
+reviewed_by: null
+reviewed_at: null
+confidence: medium
+entities:
+  - api/src/controllers/login.js
+  - api/src/public/login/script.js
+  - api/src/templates/login/token-login.html
+concepts:
+  - token-based (passwordless) authentication
+  - user-agent based browser detection
+  - Safari compatibility gating
+  - consistent login-flow UX across entry points
+related_issues:
+  - cht-core-6784
+stale: false
+---
+
+## Problem
+
+After #6784 hid login fields for Safari users, the token_login path was left uncovered: a token_login link opened in Safari would still complete authentication, putting Safari users into a flow that is otherwise intentionally blocked/unsupported. The behavior was inconsistent with the main login page.
+
+## Root Cause
+
+The shared login script (api/src/public/login/script.js) is also loaded by api/src/templates/login/token-login.html. Its `DOMContentLoaded` handler called `requestTokenLogin()`, which POSTs to `document.getElementById('tokenLogin')?.action` (the token URL, rendered from `req.url`), before `checkUnsupportedBrowser()`, so the Safari check from #6784 ran only after the login request had been sent. api/src/templates/login/token-login.html also lacked the `id="unsupported-browser"` element and the lib-bowser.js include. In api/src/controllers/login.js, the `tokenLogin` template's `translationStrings` had no unsupported-browser keys, so the message could not render there. Neither before nor after this PR does the server-side token-login handler check the user agent.
+
+## Solution
+
+- api/src/public/login/script.js: added `shouldBlockBrowser()`, which at this PR returns `isSafariBrowser()`, and moved `checkUnsupportedBrowser()` ahead of the token-login branch of the `DOMContentLoaded` handler. It now calls `requestTokenLogin()` only when `!shouldBlockBrowser()`. On Safari, `checkUnsupportedBrowser()` now also hides `.locale-wrapper .loading`, the token page's "Logging you in. Please wait." text and spinner, alongside the login form's `getElementById('login-fields')` wrapper.
+- api/src/templates/login/token-login.html: added the `id="unsupported-browser"` paragraph and a `<script src="/login/lib-bowser.js">` include.
+- api/src/controllers/login.js: added `login.unsupported_browser` and `login.unsupported_browser.safari` to the `tokenLogin` template's `translationStrings`, so the message text reaches that page.
+
+The block is client-side. The script withholds the token POST, and the token-login endpoint itself is unchanged.
+
+## Code Patterns
+
+Run the browser check before any action that fires on page load. In api/src/public/login/script.js, `checkUnsupportedBrowser()` runs first, and the auto-submitting `requestTokenLogin()` is gated on `!shouldBlockBrowser()`, which reuses `isSafariBrowser()` from #6784. Each server-rendered login template receives only the translation keys listed in its entry of the `templates` object in api/src/controllers/login.js (read as `templates[page].translationStrings`). Showing a message on another page therefore needs its keys added there as well as the element in the template (api/src/templates/login/token-login.html).
+
+## Design Choices
+
+Mirror the main login page's Safari-blocking UX and messaging rather than inventing a separate token_login flow, keeping the experience consistent across all login entry points and reusing the prior #6784 detection rather than introducing new detection logic. The new `shouldBlockBrowser()` only wraps `isSafariBrowser()`, so the token gate names a policy rather than a browser (the reviewer asked for "a function that will return whether the app is safe to use or not", with Safari the only case at this point). It is kept separate from `checkUnsupportedBrowser()` because that function returns early when `selectedLocale` is unset and only shows the message and hides elements; the reviewer required a block that does not depend on translations (PR #10502 review thread on script.js:207, 2026-01-12; commit c124751d34). At this PR, `checkUnsupportedBrowser()` still tests `isSafari` directly when hiding elements. On master, PR #10992 extended `shouldBlockBrowser()` to also return true for Chrome below 90, and `checkUnsupportedBrowser()` now uses it too.
+
+## Related Files
+
+- api/src/controllers/login.js
+- api/src/public/login/script.js
+- api/src/templates/login/token-login.html
+
+## Testing
+
+No tests were added or changed. The diff touches only api/src/controllers/login.js, api/src/public/login/script.js and api/src/templates/login/token-login.html.
+
+## Related Issues
+
+- #10494: "Prevent logging in with token in Safari Browser" — this draft's issue
+- #6784: "Alert Safari users CHT doesn't support their browser" — the prior change (PR #10414) that added `isSafariBrowser()` and hid the main login page's fields, which this PR extends to token login
+
+## Domain Rationale
+
+**Fit:** strong
+
+The PR decides whether a token login can happen in Safari: the token-login page's script no longer submits the token there (#10494, "Prevent logging in with token in Safari Browser"). That gates a login mechanism, which is authentication. Enforcement is client-side only: the token-login endpoint is unchanged and performs no browser check, and no credential, session or token handling changed.
diff --git a/agent-memory/domains/authentication/issues/10599-fix10386-fix-offline-user-and-admin-role-detection.md b/agent-memory/domains/authentication/issues/10599-fix10386-fix-offline-user-and-admin-role-detection.md
new file mode 100644
index 00000000..706acab4
--- /dev/null
+++ b/agent-memory/domains/authentication/issues/10599-fix10386-fix-offline-user-and-admin-role-detection.md
@@ -0,0 +1,100 @@
+---
+id: cht-core-10386
+category: bug
+domain: authentication
+domainFit: strong
+issueNumber: 10386
+issueUrl: https://github.com/medic/cht-core/issues/10386
+title: Fix offline-user/admin role detection so the online `admin` role no longer gets a purge database
+lastUpdated: '2026-09-29'
+summary: Purge databases (e.g. `medic-purged-role-…`) were being created for the online `admin` role, wasting >6GB and daily processing time. The fix makes sentinel's purging call `roles.isOffline` from `@medic/user-management` instead of its own copy in `purging-utils`, and makes the user-management role checks treat `admin` as well as `_admin` as a DB admin role; `isOffline` also now returns false for an empty roles array.
+services:
+  - sentinel
+  - api
+techStack:
+  - javascript
+  - nodejs
+  - couchdb
+tags:
+  - purging
+  - offline-roles
+  - admin-role
+  - role-detection
+  - isOffline
+  - purge-databases
+related_workflows: []
+source_pr: medic/cht-core#10599
+source_sha: d38cb4a56dd9110662186aec321cf78986c055fc
+distilled_at: '2026-06-22'
+reviewed_by: null
+reviewed_at: null
+confidence: medium
+entities:
+  - shared-libs/user-management/src/roles.js
+  - shared-libs/user-management/src/users.js
+  - sentinel/src/lib/purging.js
+  - shared-libs/purging-utils/src/index.js
+concepts:
+  - role-based user classification
+  - offline-first replication
+  - document purging
+  - online vs offline users
+  - centralized role detection
+related_issues: []
+stale: true
+---
+
+## Problem
+
+On the Nairobi instance, purge databases such as `medic-purged-role-6ed8e2e23ed4cf28156a7cd33ccc3f94` were being created for the `admin` role, which is an online role and should have no purge database. This wasted over 6GB of disk space and significant daily processing time, and purging was already struggling to complete on the instance.
+
+## Root Cause
+
+Offline detection was duplicated. Sentinel's purge setup (`getRoles()` in `sentinel/src/lib/purging.js`) used the `isOffline` in `shared-libs/purging-utils/src/index.js` (`const isOffline = (configured, roles) =>`). Its online check (`isOnlineOnly`) recognised only `mm-online` and `_admin`, and a user with no role defined in `app_settings.roles` counted as offline. Admins now carry an `admin` role in their user doc instead of `_admin`, and `admin` is not a configured role, so admin users were classed as offline and got a purge database. The separate `isOffline` in `shared-libs/user-management/src/roles.js` (`isOffline: roles => {`, called as `roles.isOffline`; the commit message writes `user-management.roles.isOffline`) excluded only `_admin`, via `isDbAdmin`, and returned true for an empty roles array.
+
+## Solution
+
+- `sentinel/src/lib/purging.js`: `getRoles()`, rewritten as an async function, now takes `roles` from `require('@medic/user-management')(config, db, dataContext)` and calls `roles.isOffline(userRoles)`. It still skips users whose roles are missing or empty.
+- `shared-libs/purging-utils/src/index.js`: its `isOffline`, `isOnlineOnly` and `DB_ADMIN_ROLE = '_admin'` were deleted, and the module no longer exports `isOffline`.
+- `shared-libs/user-management/src/roles.js`: `isDbAdmin()` and `hasOnlineRole()` treat both `admin` and `_admin` as DB admin roles. At this PR that is a local `DB_ADMIN_ROLES = ['admin', '_admin']`; on master the list is imported from `@medic/constants`, where PR #10795 moved it. `isOffline` returns `false` for an empty array. It now excludes any online-only user (`isOnlineOnly`, meaning an `admin`, `_admin` or `mm-online` role) rather than only `_admin`. Otherwise a user is still offline when none of their roles is configured or any configured role has `offline: true`. lodash was dropped from the file.
+- `shared-libs/user-management/src/users.js`: `missingFields()` now reports `type or roles` as missing for an empty roles array. Before, it treated such a user as offline and required `place` and `contact`.
+
+`isDbAdmin()` also backs api's admin checks: `auth.isDbAdmin` and `hasAllPermissions()` in `api/src/auth.js`, plus the couch-config, credentials, login and replication-limit-log controllers. Those checks now accept the `admin` role as well.
+
+## Code Patterns
+
+Keep cross-cutting role checks in `shared-libs/user-management/src/roles.js` (e.g. `isOffline`, `isDbAdmin`). Consumers such as `sentinel/src/lib/purging.js` get them via `const { roles } = require('@medic/user-management')(config, db, dataContext)` instead of keeping their own copy; the copy in `shared-libs/purging-utils` was deleted. Treat empty roles and online-only roles (`admin`, `_admin`, `mm-online`) as not offline.
+
+## Design Choices
+
+Offline detection was consolidated into a single implementation in user-management roles instead of a separate purging-specific copy, so the two cannot diverge. Inside `isOffline`, the separate `_admin` check was replaced by `isOnlineOnly`, so `isOffline` and `isOnlineOnly` share one definition of online roles (`hasOnlineRole`).
+
+## Related Files
+
+- sentinel/src/lib/purging.js
+- sentinel/tests/unit/lib/purging.spec.js
+- shared-libs/purging-utils/src/index.js
+- shared-libs/purging-utils/test/index.js
+- shared-libs/user-management/src/roles.js
+- shared-libs/user-management/src/users.js
+- shared-libs/user-management/test/unit/roles.spec.js
+- shared-libs/user-management/test/unit/users.spec.js
+
+## Testing
+
+All four test files were modified; none were added.
+
+- `shared-libs/user-management/test/unit/roles.spec.js` replaces "should return true for an empty array and for roles that are not configured" with separate `isOffline` cases: "should return false empty array", "should return true for roles that are not configured", "should return false for empty roles", "should return false for db admins" (both `_admin` and `admin`), and "should return false for mm-online role".
+- `shared-libs/user-management/test/unit/users.spec.js` replaces the catch-all `config.get.returns(...)` stubs with `config.get.withArgs('roles')` and `config.get.withArgs('permissions')`, and at this PR its admin fixtures carry `['admin', 'mm-online']` (on master they are spelled `[ADMIN, ONLINE]`, from the role constants PR #10747 added).
+- `sentinel/tests/unit/lib/purging.spec.js` now stubs `roles.isOffline` instead of `purgingUtils.isOffline`; no purge-database assertions were added.
+- `shared-libs/purging-utils/test/index.js` drops its `isOffline` cases along with the function.
+
+## Related Issues
+
+- #10386: "Purge database created for admin role" (this draft's issue)
+
+## Domain Rationale
+
+**Fit:** strong
+
+The fix is to role classification in `shared-libs/user-management/src/roles.js`: which roles count as DB admin (`isDbAdmin`), as online (`hasOnlineRole`/`isOnlineOnly`) and as offline (`isOffline`). The `isDbAdmin` change also widens api's admin checks to the `admin` role. Purging is where the bug showed; sentinel's change there only swaps its private copy of the check for the shared one.
diff --git a/agent-memory/domains/authentication/issues/10795-fix10341-revoke-permissions-when-user-role-is-deleted-from-a.md b/agent-memory/domains/authentication/issues/10795-fix10341-revoke-permissions-when-user-role-is-deleted-from-a.md
new file mode 100644
index 00000000..fc39b767
--- /dev/null
+++ b/agent-memory/domains/authentication/issues/10795-fix10341-revoke-permissions-when-user-role-is-deleted-from-a.md
@@ -0,0 +1,122 @@
+---
+id: cht-core-10341
+category: bug
+domain: authentication
+domainFit: strong
+issueNumber: 10341
+issueUrl: https://github.com/medic/cht-core/issues/10341
+title: Revoke permissions when a user's role is deleted from app_settings by filtering effective roles against configured roles
+lastUpdated: '2026-09-29'
+summary: Users kept permissions granted by a role even after that role was deleted in Admin, because permission checks never verified the role still existed in app_settings.roles. Fixed in cht-datasource's `hasPermissions`/`hasAnyPermission`, which now read settings from the data context and drop any role missing from `app_settings.roles` (DB admin roles are always kept) before evaluating permissions; api's and user-management's own permission lookups were replaced by calls to these functions.
+services:
+  - api
+  - webapp
+  - admin
+  - sentinel
+techStack:
+  - javascript
+  - typescript
+  - angular
+  - angularjs
+  - couchdb
+tags:
+  - permissions
+  - roles
+  - authorization
+  - access-control
+  - app_settings
+  - role-deletion
+  - rbac
+  - security
+related_workflows: []
+source_pr: medic/cht-core#10795
+source_sha: 058554e4d34702a7918bab261bf07dc550c09e53
+distilled_at: '2026-06-22'
+reviewed_by: null
+reviewed_at: null
+confidence: medium
+entities:
+  - shared-libs/cht-datasource/src/auth.js
+  - shared-libs/user-management/src/roles.js
+  - api/src/auth.js
+  - webapp/src/ts/services/cht-datasource.service.ts
+  - shared-libs/constants/src/index.js
+concepts:
+  - role-based access control
+  - permission evaluation
+  - centralized authorization logic
+  - passive (backwards-compatible) permission-check signatures
+  - restrictive default when roles config is absent
+related_issues: []
+stale: true
+---
+
+## Problem
+
+When an admin deleted a role via Admin > Roles & Permissions, the role was removed from app_settings.roles but its entries in app_settings.permissions remained. Permission checks honored those stale entries, so a user assigned the deleted role retained its permissions indefinitely — e.g. after syncing/reloading, the user could still view the contacts tab even though the role granting that access had been deleted (issue #10341).
+
+## Root Cause
+
+All three permission-checking codepaths evaluated a user's roles only against app_settings.permissions and never cross-referenced app_settings.roles. Before this PR those were cht-datasource's `hasPermissions()`/`hasAnyPermission()` in shared-libs/cht-datasource/src/auth.js, and the private `hasPermission()` helpers behind `hasAllPermissions()` in shared-libs/user-management/src/roles.js and api/src/auth.js, both of which read `config.get('permissions')`. Deleting a role removed it from roles but left dangling references in permissions that were still treated as valid.
+
+## Solution
+
+The filtering lives in cht-datasource, and the other two codepaths now delegate to it.
+
+- `shared-libs/cht-datasource/src/auth.js`: the internal `hasPermissions` and `hasAnyPermission` became curried on the data context, `(ctx) => (permissions, userRoles, chtPermissionsSettings)`, and read settings internally with `ctx.settings.getAll()`. Permissions come from `settings.permissions` unless the caller passes `chtPermissionsSettings`, which is now a deprecated override. Roles always come from `settings.roles`. For a non-admin user, the new internal helper `filterRolesByConfigured` (`const filterRolesByConfigured = (userRoles, chtRolesSettings = {}) =>`) keeps only roles that are keys of `settings.roles` or in `DB_ADMIN_ROLES`, and does so before any permission lookup. `isAdmin()` now accepts any role in `DB_ADMIN_ROLES` (`admin` and `_admin`), where before it accepted only `_admin`.
+- Public API: `v1.hasPermissions` and `v1.hasAnyPermission` on the object `getDatasource` returns keep their argument order (shared-libs/cht-datasource/src/index.ts: `ctx.bind(hasPermissions)(permissions, userRoles, chtPermissionsSettings)` and `ctx.bind(hasAnyPermission)(permissionsGroupList, userRoles, chtPermissionsSettings)`) and call the curried functions through `ctx.bind`, so existing two- and three-argument callers still work. `DataContext` must now carry a `settings` service, and `getRemoteDataContext` takes that service as a new first parameter (`export const getRemoteDataContext = (settings: SettingsService, url = '')`). The `SettingsService` type moved to `shared-libs/cht-datasource/src/libs/data-context.ts`.
+- `api/src/auth.js`: its private `hasPermission(userCtx, permission)` was removed. `assertPermissions()` now calls `datasource.v1.hasPermissions(hasAll, userCtx.roles)` and `datasource.v1.hasAnyPermission(hasAny.map(perm => [perm]), userCtx.roles)`, and the exported `hasAllPermissions` calls `getDatasource(dataContext).v1.hasPermissions(permissions, userCtx.roles)`.
+- `shared-libs/user-management/src/roles.js`: the private `hasPermission()` and the exported `hasAllPermissions()` were removed, and `DB_ADMIN_ROLES` moved to `@medic/constants` (`shared-libs/constants/src/index.js`). `shared-libs/user-management/src/users.js` now checks `can_skip_password_change` (in `isPasswordChangeRequired`) and `can_have_multiple_places` (in `validateAllowedMultipleFacilities`) through `getDatasource(dataContext).v1.hasPermissions`.
+- `webapp/src/ts/services/cht-datasource.service.ts`: online-only users now get `getRemoteDataContext(settingsService)`, backed by the same settings service as the local context. The `getChtPermissionsFromSettings()` helper was removed, and the `hasPermissions`/`hasAnyPermission` wrappers forward only `chtSettings?.permissions` as the override.
+- Admin app: the `DataContext` service (`admin/src/js/services/data-context.js`) now resolves to a promise. It loads `Settings()` first and refreshes its cached settings whenever the settings doc changes. `Auth` (`admin/src/js/services/auth.js`), `admin/src/js/controllers/edit-user.js` and `admin/src/js/services/search.js` wait on that promise, and no longer pass `settings.permissions` in.
+
+## Code Patterns
+
+Data-context-bound permission checks: define the function curried on the data context, as in `const hasPermissions = (ctx) => (permissions, userRoles, chtPermissionsSettings) =>`, read current settings synchronously with `ctx.settings.getAll()`, and expose it from `getDatasource` through `ctx.bind(hasPermissions)(permissions, userRoles, chtPermissionsSettings)`. Keep a legacy settings argument as an optional override (`chtPermissionsSettings ?? settings.permissions`) so older call sites keep working. Apply `filterRolesByConfigured` after the admin short-circuit and before the permission lookup. In api and user-management, call `getDatasource(dataContext).v1.hasPermissions` rather than re-implementing the lookup.
+
+## Design Choices
+
+- One implementation instead of three: the private permission lookups in api and user-management were deleted, and those checks now route through cht-datasource, so the role filter is applied in one place.
+- Passive changes to the permission functions: the cht-datasource permission functions are also called by deployment config code (contact-summary, and tasks/targets through the rules engine's `cht` API) and by purge functions that sentinel runs. The public `v1.hasPermissions`/`v1.hasAnyPermission` signatures therefore stayed compatible, and the settings they now need come from the data context's `SettingsService` rather than from a new parameter. Sentinel still passes `config.get('permissions')` to purge functions, which may forward it as the override.
+- Restrictive default: when `settings.roles` is absent or `{}`, `filterRolesByConfigured` keeps only DB admin roles, so non-admin users get no permissions. The spec "should return false when no roles are configured and user is not admin" pins this behaviour. The PR description still says an empty or absent `roles` config falls back to no filtering; the merged code does not.
+
+## Related Files
+
+- shared-libs/cht-datasource/src/auth.js
+- shared-libs/cht-datasource/src/index.ts
+- shared-libs/cht-datasource/src/libs/core.ts
+- shared-libs/cht-datasource/src/libs/data-context.ts
+- shared-libs/cht-datasource/src/local/libs/data-context.ts
+- shared-libs/cht-datasource/src/remote/libs/data-context.ts
+- shared-libs/user-management/src/roles.js
+- shared-libs/user-management/src/users.js
+- api/src/auth.js
+- webapp/src/ts/services/cht-datasource.service.ts
+- shared-libs/constants/src/index.js
+- admin/src/js/controllers/edit-user.js
+- admin/src/js/services/auth.js
+- admin/src/js/services/data-context.js
+- admin/src/js/services/search.js
+
+## Testing
+
+All touched test files were modified; none were added.
+
+- cht-datasource: `shared-libs/cht-datasource/test/auth.spec.js` builds a fake context (`makeCtx(settings)`). It adds cases for a deleted role ("should return false when the user role has been deleted from the configured roles"), a still-configured role, no roles configured (`{}` or `undefined`, where a non-admin gets no permissions), each role in `DB_ADMIN_ROLES`, and the `chtPermissionsSettings` override (used when given, otherwise `settings.permissions`). `shared-libs/cht-datasource/test/index.spec.ts`, `shared-libs/cht-datasource/test/libs/core.spec.ts`, `shared-libs/cht-datasource/test/libs/data-context.spec.ts` and `shared-libs/cht-datasource/test/remote/libs/data-context.spec.ts` cover the settings-carrying data context.
+- user-management: the `hasAllPermissions` cases were removed from `shared-libs/user-management/test/unit/roles.spec.js`, and `shared-libs/user-management/test/unit/users.spec.js` was updated.
+- api: `api/tests/mocha/auth.spec.js`, plus the bulk-docs and settings controller specs.
+- admin: the edit-user, auth and data-context specs; the data-context spec covers the refresh on settings-doc changes.
+- webapp karma: `webapp/tests/karma/ts/services/auth.service.spec.ts` and `webapp/tests/karma/ts/services/cht-datasource.service.spec.ts`, whose mock settings now include `roles`.
+- sentinel: `sentinel/tests/unit/lib/purging.spec.js` now calls `chtScript.v1.hasPermissions`/`hasAnyPermission` from a purge function without a settings argument.
+- Integration: the cht-datasource contact/person/place/report/target specs pass a settings service to `getRemoteDataContext`, and `tests/integration/api/controllers/users.spec.js` configures a `program_officer` role.
+- e2e: the purge spec (`tests/e2e/default/purge/purge.wdio-spec.js`) dropped the settings argument from its purge function's `hasPermissions` call. That spec is present at this PR's anchor but was removed on master by PR #11139 ("adds archiving").
+
+## Related Issues
+
+- #10341: "Deleting roles does not result in users with those roles losing permission" (this draft's issue)
+
+## Domain Rationale
+
+**Fit:** strong
+
+The PR changes how permission checks resolve a user's roles: roles no longer present in `app_settings.roles` stop granting permissions, and the api and user-management checks now share cht-datasource's implementation. That is role-based access control. The contacts tab in the issue's repro is only the symptom.
diff --git a/agent-memory/domains/authentication/issues/10827-fix9834-make-login-page-responsive-to-ltr-rtl-switching.md b/agent-memory/domains/authentication/issues/10827-fix9834-make-login-page-responsive-to-ltr-rtl-switching.md
new file mode 100644
index 00000000..e8e99866
--- /dev/null
+++ b/agent-memory/domains/authentication/issues/10827-fix9834-make-login-page-responsive-to-ltr-rtl-switching.md
@@ -0,0 +1,97 @@
+---
+id: cht-core-9834
+category: improvement
+domain: authentication
+domainFit: weak
+issueNumber: 9834
+issueUrl: https://github.com/medic/cht-core/issues/9834
+title: Make the login and token-login pages switch layout direction (LTR ↔ RTL) with the selected locale without a reload, and render all three login templates with the default locale's direction
+lastUpdated: '2026-09-29'
+summary: The login, password-reset and token-login pages use their own JS, CSS and templates and stayed LTR for RTL languages, unlike the main webapp. The fix carries each translation doc's rtl flag into the login controller, renders <html dir> from the default locale's direction plus a data-rtl attribute on each RTL locale link, and has setDirection() in auth-utils.js set document.documentElement.dir from the selected locale's link (ltr when no such link is rendered) on load and on every locale change. RTL CSS mirrors the password field and its toggle.
+services:
+  - api
+techStack:
+  - javascript
+  - css
+  - html
+  - couchdb
+  - mocha
+tags:
+  - rtl
+  - ltr
+  - i18n
+  - login-page
+  - localization
+  - bidirectional-text
+  - responsive-layout
+related_workflows: []
+source_pr: medic/cht-core#10827
+source_sha: 5b4670614d7bd46a4d47d01e30941adb3d60c3d8
+distilled_at: '2026-06-22'
+reviewed_by: null
+reviewed_at: null
+confidence: medium
+entities:
+  - api/src/controllers/login.js
+  - api/src/public/login/auth-utils.js
+  - api/src/public/login/style.css
+  - api/src/templates/login/index.html
+  - api/src/templates/login/password-reset.html
+  - api/src/templates/login/token-login.html
+concepts:
+  - internationalization
+  - bidirectional-text-rtl-layout
+  - server-side-template-rendering
+  - client-side-direction-switching
+  - locale-translation-documents
+  - data-attribute-server-to-client-handoff
+related_issues: []
+stale: false
+---
+
+## Problem
+
+The CHT webapp supports RTL languages, but the login page does not — it has its own JavaScript library, stylesheets, and templates for language switching. Selecting an RTL language on the login or token-login page left the layout LTR, and none of the three login templates (api/src/templates/login/index.html, api/src/templates/login/token-login.html, api/src/templates/login/password-reset.html) set `dir` on `<html>`, so RTL users got an LTR layout.
+
+## Root Cause
+
+The login pages are rendered independently of the main webapp with their own api/src/public/login/auth-utils.js, api/src/public/login/style.css, and templates that had no awareness of locale text direction. The login controller did not expose which locales are RTL (its `getEnabledLocales()` mapped translation docs to `{ key: doc.code, label: doc.name }` only), the client-side translation routine (baseTranslate) never set the <html dir> attribute, and the password-visibility toggle icon was absolutely positioned for LTR only.
+
+## Solution
+
+- api/src/controllers/login.js: `getEnabledLocales()` now maps each enabled translation doc to `{ key: doc.code, label: doc.name, rtl: doc.rtl || false }`. It no longer empties the list when fewer than two locales are enabled. `render()` does that instead: it passes `selectorLocales = locales.length < 2 ? [] : locales` as `locales` and computes `defaultLocale` via `getBestLocaleCode()`. It also passes `defaultDir`, which is `'rtl'` when the default locale's entry has `rtl` set and `'ltr'` otherwise.
+- Templates: api/src/templates/login/index.html, api/src/templates/login/token-login.html and api/src/templates/login/password-reset.html render `<html dir="{{ defaultDir }}">`, and api/src/templates/login/password-reset.html drops its `lang="en"`. The `class="locale"` links in api/src/templates/login/index.html and api/src/templates/login/token-login.html get `data-rtl="true"` when `locale.rtl` is set. api/src/templates/login/password-reset.html has no locale selector.
+- api/src/public/login/auth-utils.js: the new `setDirection` (`const setDirection = (locale) =>`) finds the `.locale[name="${locale}"]` link. It sets `document.documentElement.dir` to `'rtl'` if that link has `data-rtl`, else `'ltr'`. `baseTranslate()` calls it first, so it runs on load and on every locale click (`handleLocaleSelection` → `translate()` in api/src/public/login/script.js → `baseTranslate()` from api/src/public/login/auth-utils.js). It is also exported on `window.AuthUtils`. The body attributes `data-default-locale` and `data-translations` are now read via `document.body.dataset.defaultLocale` and `dataset.translations`.
+- api/src/public/login/style.css: `[dir="rtl"] #password-container #password` mirrors the input padding (`6px 10px 6px 43px`). `[dir="rtl"] #password-container #password-toggle` moves the absolutely-positioned toggle to `left: 0` (`right: auto`).
+
+## Code Patterns
+
+Server-to-client handoff via a per-element data attribute. The controller adds `rtl` to each locale entry. In api/src/templates/login/index.html and api/src/templates/login/token-login.html the templates emit it as `data-rtl="true"` on that locale's link. Client JS reads it back: `localeLink?.dataset.rtl` in `setDirection()` (api/src/public/login/auth-utils.js). The server also renders the initial `<html dir="{{ defaultDir }}">`, so the page starts in the default locale's direction before any script runs. Reload-free direction switching: `setDirection()` is called from `baseTranslate()`, the routine that every load and locale change goes through. RTL-aware styling via [dir="rtl"] attribute selectors to mirror absolutely-positioned elements (api/src/public/login/style.css).
+
+## Design Choices
+
+The RTL flag comes from the `rtl` field of the `messages-*` translation docs, not from a list in the login code. The webapp reads the same field (`doc.rtl && this.languageService.setRtlLanguage(locale)` in webapp/src/ts/providers/translation-loader.provider.ts). For bundled languages, api/src/translations.js writes that field from its `RTL_LANGUAGES` list (`['ar']` at this PR), so a new bundled RTL language still needs that list updated. A translation doc that already carries `rtl: true` is picked up with no code change. Direction is switched client-side without a page reload by hooking baseTranslate, giving an instant layout flip on locale selection. As written, though, `setDirection()` takes the direction only from the matching `.locale` link. Where no such link is rendered, the client sets `ltr` once the script runs and overrides the server-rendered `dir`. That always happens on api/src/templates/login/password-reset.html, which has no locale selector and whose api/src/public/login/password-reset.js calls `baseTranslate()` on load. It also happens on api/src/templates/login/index.html and api/src/templates/login/token-login.html when fewer than two locales are enabled, because the selector is then not rendered.
+
+## Related Files
+
+- api/src/controllers/login.js
+- api/src/public/login/auth-utils.js
+- api/src/public/login/style.css
+- api/src/templates/login/index.html
+- api/src/templates/login/password-reset.html
+- api/src/templates/login/token-login.html
+- api/tests/mocha/controllers/login.spec.js
+
+## Testing
+
+Added two Mocha tests to api/tests/mocha/controllers/login.spec.js: 'sets defaultDir to rtl when the default locale is RTL' and 'sets defaultDir to ltr when the default locale is not RTL'. They stub `translations.getEnabledLocales()` with `rtl`-flagged docs and a `{{ defaultDir }}` template, and assert the rendered login page. There are no client-side tests for `setDirection()` or the RTL CSS.
+
+## Related Issues
+
+- #9834: "Make login page responsive to LTR <-> RTL switching" — this draft's issue, which asks to extend the webapp's RTL support to the login page templates and scripts
+
+## Domain Rationale
+
+**Fit:** weak
+
+Every changed file serves the login, password-reset and token-login pages: the login controller, templates, client scripts and CSS under api/src/.../login. The change itself is i18n and layout, making those pages follow the locale's text direction, and it touches no credential, session or access handling. Authentication is the least-bad home because the login pages are the only surface touched. It adds no translations and registers no locales, so it is not configuration either.
diff --git a/agent-memory/domains/authentication/issues/10994-fix10631-support-ui-extension-type-in-db-validation.md b/agent-memory/domains/authentication/issues/10994-fix10631-support-ui-extension-type-in-db-validation.md
new file mode 100644
index 00000000..a2f81e7d
--- /dev/null
+++ b/agent-memory/domains/authentication/issues/10994-fix10631-support-ui-extension-type-in-db-validation.md
@@ -0,0 +1,89 @@
+---
+id: cht-core-10631
+category: improvement
+domain: authentication
+domainFit: strong
+issueNumber: 10631
+issueUrl: https://github.com/medic/cht-core/issues/10631
+title: Enforce admin-only write access for ui-extension doc type in validate_doc_update
+lastUpdated: '2026-10-05'
+summary: The medic ddoc's `validate_doc_update` did not treat `ui-extension` docs as admin-only, so non-admin users could create or edit them. The fix adds `'ui-extension'` to `ADMIN_ONLY_TYPES`, so non-admin writes of docs with `type` `ui-extension` are rejected while DB admins can still write them.
+services:
+  - api
+techStack:
+  - javascript
+  - couchdb
+tags:
+  - authorization
+  - access-control
+  - admin-only
+  - ui-extension
+  - validate_doc_update
+  - couchdb-validation
+related_workflows:
+  - ui-extensions
+source_pr: medic/cht-core#10994
+source_sha: d5bd8c1fe9098ae310ee7e82ddeed4b44120e370
+distilled_at: '2026-06-22'
+reviewed_by: null
+reviewed_at: null
+confidence: medium
+entities:
+  - ddocs/medic-db/medic/validate_doc_update.js
+concepts:
+  - document write validation
+  - admin-only doc types
+  - authorization
+  - CouchDB validate_doc_update
+  - database-level access control
+related_issues:
+  - cht-core-10224
+stale: true
+---
+
+> **Epic child.** PR #10994 was squash-merged into the feature branch `10224-ui-extensions`
+> (`d5bd8c1fe`, 2026-05-11), not into master. That branch reached master as PR #11050
+> (`180c29ecf`, 2026-06-23). Its own PR number is stamped nowhere on master, which is
+> why this draft's `source_sha` does not resolve in a plain clone. Fetch it with
+> `git fetch origin +refs/pull/11050/head:refs/verify/pr11050` — the epic PR's head ref.
+
+## Problem
+
+UI extensions are docs in the medic database with `_id` `ui-extension:<name>`, carrying an `extension.js` script attachment that the webapp loads. The medic ddoc's `ddocs/medic-db/medic/validate_doc_update.js` reserves some doc types for DB admins through `ADMIN_ONLY_TYPES`, which then held `form`, `translations` and `token_login`. `ui-extension` was not on that list, so non-admin users could create or edit these docs directly against the database. The issue asked for the protection that `form` docs already had.
+
+## Root Cause
+
+`checkAuthority()` rejects a non-admin write with "You are not authorized to edit admin only docs" when `isAdminOnlyDoc()` matches the new or the stored revision. `isAdminOnlyDoc()` matches a `_design/` id, an id in `ADMIN_ONLY_IDS`, or a `type` in `ADMIN_ONLY_TYPES`. None of these covered `ui-extension` docs, so they passed the admin-only check like any other user doc.
+
+## Solution
+
+Appended `'ui-extension'` to `ADMIN_ONLY_TYPES` in `ddocs/medic-db/medic/validate_doc_update.js`, making it `[ 'form', 'translations', 'token_login', 'ui-extension' ]`; this is the only line the PR changes. A non-admin write in which either the new or the stored revision has its `type` set to `'ui-extension'` is now rejected with that forbidden error, while DB admins (`isDbAdmin()`) return before the check. The file is byte-identical at this PR, at the epic squash `180c29ecf`, and on master.
+
+## Code Patterns
+
+To make a doc type writable only by DB admins, add its `type` string to `ADMIN_ONLY_TYPES` in ddocs/medic-db/medic/validate_doc_update.js (for fixed ids, `ADMIN_ONLY_IDS`); `checkAuthority()` then rejects non-admin writes through `isAdminOnlyDoc()`. `form`, `translations` and `token_login` are protected the same way.
+
+## Design Choices
+
+The restriction sits in the medic ddoc's `validate_doc_update`, which CouchDB runs on every write to the medic database. It therefore applies to direct CouchDB requests, writes proxied by api, and replication alike, rather than depending on application-layer checks.
+
+The check keys on `type`, not on the `ui-extension:` id prefix. At this PR's anchor the api's loader (`api/src/services/ui-extension.js`) still selected extension docs by id prefix alone. Later commits on the feature branch made it also require the doc's `type` to be `'ui-extension'` (`doc.type === TYPE`, fee56a829, "Update api to check type of ui-extension docs when loading") and then removed the api's ui-extension endpoints (09391e322), so that file is not on master. On master the loader is the webapp's webapp/src/ts/services/ui-extensions.service.ts: it reads ids under `PREFIXES.UI_EXTENSION` and keeps only docs with `type === DOC_TYPES.UI_EXTENSION`, which is the type this check protects.
+
+## Related Files
+
+- ddocs/medic-db/medic/validate_doc_update.js
+
+## Testing
+
+No automated test covers the new type: the PR changed only `ddocs/medic-db/medic/validate_doc_update.js`, and `webapp/tests/mocha/unit/validate_doc_update.spec.js` has no `ui-extension` case, either at this PR or on master. The PR description records a manual check instead, run directly against CouchDB (`localhost:5984/medic`): an admin (`medic`) `POST` of `{"_id": "ui-extension:hello-world", "type": "ui-extension"}` returned `{"ok": true, ...}`, and a `POST` of `{"_id": "ui-extension:non-admin-test", "type": "ui-extension"}` as the non-admin user `testuser` returned `{"error": "forbidden", "reason": "You are not authorized to edit admin only docs"}`. This is the manual test the issue asked for in place of automated tests.
+
+## Related Issues
+
+- #10631: "Update `medic` db validation to support `ui-extension` doc type" (this draft's issue)
+- #10224: "Support custom UI Extensions" — the epic whose feature branch this PR merged into; it reached master as PR #11050
+
+## Domain Rationale
+
+**Fit:** strong
+
+The PR's only change is to who may write a doc type: it adds `ui-extension` to the admin-only types enforced by the medic ddoc's `validate_doc_update`. That is role-based write access control. The UI extensions feature itself (loading, rendering, configuration) is outside this change; `related_workflows: [ui-extensions]` links the draft to that workstream.
diff --git a/agent-memory/domains/authentication/issues/8675-feat6530-add-rate-limiting-for-authentication-requests.md b/agent-memory/domains/authentication/issues/8675-feat6530-add-rate-limiting-for-authentication-requests.md
new file mode 100644
index 00000000..b56947e9
--- /dev/null
+++ b/agent-memory/domains/authentication/issues/8675-feat6530-add-rate-limiting-for-authentication-requests.md
@@ -0,0 +1,92 @@
+---
+id: cht-core-6530
+category: feature
+domain: authentication
+domainFit: strong
+issueNumber: 6530
+issueUrl: https://github.com/medic/cht-core/issues/6530
+title: Add rate limiting for authentication requests
+lastUpdated: '2026-09-29'
+summary: Authentication had no throttling, leaving the login form and HTTP Basic auth open to brute-force and credential-stuffing attacks. A rate-limit service (an in-memory `rate-limiter-flexible` limiter) and a global Express middleware now count failed attempts (401/429 responses) per client IP, username and password, and answer further credentialed requests with 429 Too Many Requests once a key has 10 failures within 10 seconds.
+services:
+  - api
+techStack:
+  - javascript
+  - node.js
+  - express
+tags:
+  - rate-limiting
+  - login
+  - brute-force-protection
+  - security
+  - middleware
+  - throttling
+related_workflows: []
+source_pr: medic/cht-core#8675
+source_sha: 1332879f0c73965687ae5dfe80373cde28b402d2
+distilled_at: '2026-06-23'
+reviewed_by: null
+reviewed_at: null
+confidence: medium
+entities:
+  - api/src/middleware/rate-limiter.js
+  - api/src/services/rate-limit.js
+  - api/src/controllers/login.js
+  - api/src/auth.js
+  - api/src/server-utils.js
+  - api/src/routing.js
+  - api/src/public/login/script.js
+concepts:
+  - rate limiting
+  - brute-force protection
+  - express middleware
+  - authentication throttling
+  - service/middleware separation
+related_issues: []
+stale: false
+---
+
+## Problem
+
+API authentication (the login form endpoints and HTTP Basic auth on any API request) accepted unlimited repeated attempts from a client with no throttling, exposing them to brute-force and credential-stuffing attacks against user credentials.
+
+## Root Cause
+
+The login controller and auth routes lacked any request-counting or throttling layer — there was no mechanism to track or limit the number of authentication attempts per client.
+
+## Solution
+
+Introduced a dedicated rate-limit service (api/src/services/rate-limit.js) wrapping a `RateLimiterMemory` from the `rate-limiter-flexible` package (a new api dependency), configured with `keyPrefix: 'failed-login'` and 10 points per 10 seconds. Its keys are the request IP plus whichever of `req.body.user`, `req.body.password` and the HTTP Basic username/password are present; `isLimited(req)` is true when any key has no points left, and `consume(req)` spends a point on every key. The Express middleware (api/src/middleware/rate-limiter.js) is registered globally in api/src/routing.js (`app.use(rateLimiterMiddleware)`, ahead of the route handlers): a request that carries credentials and is limited gets 429, and every other request gets a `res.on('finish', ...)` handler that calls `consume` when the response status is 401 or 429, so only failed attempts are counted. JSON bodies are parsed per route (`app.postJson`), so that global pre-check only sees Basic credentials; the login handlers `post` (password login) and `tokenPost` (token login) in api/src/controllers/login.js call `rateLimitService.isLimited(req)` themselves before doing anything else. api/src/server-utils.js gained `rateLimited(req, res)`, which responds 429 `Too Many Requests`, and the login page script (api/src/public/login/script.js) now sends `Accept: application/json`, so that response comes back as JSON. The api/src/auth.js change only refactors `basicAuthCredentials`, which the service and middleware use to read Basic credentials.
+
+## Code Patterns
+
+Service + middleware separation: throttling logic lives in a reusable service (api/src/services/rate-limit.js) consumed both by a thin Express middleware (api/src/middleware/rate-limiter.js), registered globally with `app.use(rateLimiterMiddleware)` in api/src/routing.js, and by handlers that need the parsed request body (`const limited = await rateLimitService.isLimited(req);` then `return serverUtils.rateLimited(req, res);`). Penalise on the way out: because the middleware's `finish` hook spends points for every 401 or 429 response from any route, endpoints need no code of their own to have failures counted. On master the same `rateLimitService.isLimited(req)` pre-check also guards `resetPassword`, `oidcLogin` and `oidcAuthorize` in api/src/controllers/login.js.
+
+## Design Choices
+
+Rate-limit logic was factored into a standalone service rather than inlined in the login controller, so the global middleware and the login handlers share one limiter and it is unit-tested on its own. Only failures are counted — a point is spent only when the response is 401 or 429 — so successful logins do not use up the allowance. Keying on IP, username and password independently means guesses are throttled whether they come from one address, target one username, or reuse one password across usernames. The limiter is `RateLimiterMemory`, so counts are held in the API process's memory and are not persisted.
+
+## Related Files
+
+- api/src/middleware/rate-limiter.js
+- api/src/services/rate-limit.js
+- api/src/controllers/login.js
+- api/src/routing.js
+- api/src/auth.js
+- api/src/server-utils.js
+- api/src/public/login/script.js
+- api/package.json
+
+## Testing
+
+Added Mocha unit tests for the middleware (api/tests/mocha/middleware/rate-limiter.spec.js) and service (api/tests/mocha/services/rate-limit.spec.js), extended the existing login controller unit tests (api/tests/mocha/controllers/login.spec.js) with 429 cases, added an integration test (tests/integration/api/rate-limit.spec.js) asserting that the 11th failed Basic-auth request from the same IP gets 429 and that requests get 401 again after 10 seconds, and restructured tests/integration/api/routing.spec.js. The WebdriverIO specs tests/e2e/default/login/login-logout.wdio-spec.js and tests/e2e/default/translations/enabled-languages.wdio-spec.js were adjusted (for example, the login spec now fetches the branding doc once in a `before` hook).
+
+## Related Issues
+
+- #6530: "Add rate limiting to authentication endpoints" — the issue this PR closes
+
+## Domain Rationale
+
+**Fit:** strong
+
+The PR throttles failed credential checks — password and token logins plus HTTP Basic auth on any API route — to defend them against brute-force/credential-stuffing; protecting the auth/login flow is squarely the authentication domain.
diff --git a/agent-memory/domains/authentication/issues/8735-fix8689-only-get-needed-facilities.md b/agent-memory/domains/authentication/issues/8735-fix8689-only-get-needed-facilities.md
new file mode 100644
index 00000000..e57a53df
--- /dev/null
+++ b/agent-memory/domains/authentication/issues/8735-fix8689-only-get-needed-facilities.md
@@ -0,0 +1,83 @@
+---
+id: cht-core-8689
+category: bug
+domain: authentication
+domainFit: strong
+issueNumber: 8689
+issueUrl: https://github.com/medic/cht-core/issues/8689
+title: 'Users API: fetch only the place and contact docs the listed users need instead of every contact, to fix response time'
+lastUpdated: '2026-10-05'
+summary: 'The users list API (GET /api/v1/users and /api/v2/users) timed out on large instances because it loaded every contact document on the server (places and people, via the medic-client/contacts_by_type view) to resolve each user''s place and contact. The fix fetches only the place and contact docs the returned users reference, by id.'
+services:
+  - api
+techStack:
+  - javascript
+  - nodejs
+  - couchdb
+tags:
+  - performance
+  - optimization
+  - users-api
+  - facilities
+  - user-management
+related_workflows:
+  - user-registration
+source_pr: medic/cht-core#8735
+source_sha: 43a1683944df4c28dc3a7cc026bd98a10da69958
+distilled_at: '2026-06-23'
+reviewed_by: null
+reviewed_at: null
+confidence: medium
+entities:
+  - shared-libs/user-management/src/libs/facility.js
+  - shared-libs/user-management/src/users.js
+concepts:
+  - query scoping / fetch-by-id
+  - user-facility association
+  - users API enrichment
+  - performance optimization
+related_issues: []
+stale: false
+---
+
+## Problem
+
+The users API exhibited poor (slow) response times on servers with a high number of facilities — the issue reports `/api/v1/users` and `/api/v2/users` returning 504 Gateway Time-out on an instance with about 8,400 `_users` docs and 4.6 million medic docs. Listing users became progressively more expensive as the total contact count grew, because every contact doc was loaded regardless of how many users were actually being returned.
+
+## Root Cause
+
+`getList` in shared-libs/user-management/src/users.js called `getFacilities()`, which queried `medic-client/contacts_by_type` with `include_docs: true` — every place and person on the server — and then looked each user's place and contact up in that set, so the cost scaled with the total number of contacts rather than with the docs actually referenced by the users being returned.
+
+## Solution
+
+Added shared-libs/user-management/src/libs/facility.js, whose `list()` collects the users' `facility_id` values and their settings docs' `contact_id` values and fetches just those docs with one `db.medic.allDocs({ keys: Array.from(ids), include_docs: true })`; `getList` in shared-libs/user-management/src/users.js now calls it and `getFacilities()` was removed. This cuts the CouchDB reads to the docs the response needs. (On master `list()` takes only the user docs and reads both ids from them, since PR #8928 copied `contact_id` onto `_users` docs.)
+
+## Code Patterns
+
+Scope database reads to the required document IDs (fetch-by-keys) rather than loading an entire collection and filtering/joining in memory — see the facility lookup in shared-libs/user-management/src/libs/facility.js consumed by shared-libs/user-management/src/users.js.
+
+## Design Choices
+
+The author deliberately shipped a simple, high-impact partial fix: it removes the cost that scaled with the total number of contacts but acknowledges the endpoint will still degrade with very large numbers of users (the issue thread names pagination or streaming as the further work large deployments would need). Low-hanging-fruit optimization chosen over a full rewrite.
+
+## Related Files
+
+- shared-libs/user-management/src/libs/facility.js (added)
+- shared-libs/user-management/src/users.js
+- shared-libs/user-management/test/unit/libs/facility.spec.js (added)
+- shared-libs/user-management/test/unit/users.spec.js
+- tests/integration/api/controllers/users.spec.js
+
+## Testing
+
+Added unit tests for the facility lookup (shared-libs/user-management/test/unit/libs/facility.spec.js, a new file) and updated shared-libs/user-management/test/unit/users.spec.js to stub `facility.list` instead of `getFacilities`. The integration test tests/integration/api/controllers/users.spec.js adds a `POST/GET api/v2/users` case that creates ten users and checks each listed user's place and contact are hydrated; it does not measure response time.
+
+## Related Issues
+
+- #8689: "Users API not responsive" — this draft's issue: `/api/v1/users` and `/api/v2/users` timing out on a large instance
+
+## Domain Rationale
+
+**Fit:** strong
+
+The PR modifies the user-management shared library and the users API, which handle user accounts and their facility associations — squarely the user/account-management side of the authentication domain. The change is a query optimization within that domain, not a sync, contacts, or infrastructure concern.
diff --git a/agent-memory/domains/authentication/issues/8738-fix8730-fix-permission-checks-for-contact-fab-and-actionbar.md b/agent-memory/domains/authentication/issues/8738-fix8730-fix-permission-checks-for-contact-fab-and-actionbar.md
new file mode 100644
index 00000000..5cbd2054
--- /dev/null
+++ b/agent-memory/domains/authentication/issues/8738-fix8730-fix-permission-checks-for-contact-fab-and-actionbar.md
@@ -0,0 +1,96 @@
+---
+id: cht-core-8730
+category: bug
+domain: authentication
+domainFit: strong
+issueNumber: 8730
+issueUrl: https://github.com/medic/cht-core/issues/8730
+title: Fix contact FAB and actionbar permission checks to honour can_create_people
+lastUpdated: '2026-10-05'
+summary: The contacts FAB and the old actionbar's contacts-list create menu gated contact creation on `can_edit` and `can_create_places`, never on `can_create_people`, so a user with `can_create_people` but not `can_create_places` could not create people from the contact-detail FAB, and the old actionbar's contacts-list create container (place types only, Export link included) was hidden from them. The fix makes the FAB require `can_create_people` for person contact types and `can_create_places` for place types, and lets the old actionbar's contacts-list create links show for either permission.
+services:
+  - webapp
+techStack:
+  - typescript
+  - angular
+  - html
+  - webdriverio
+  - karma
+tags:
+  - permissions
+  - can_create_people
+  - can_create_places
+  - authorization
+  - fab
+  - actionbar
+  - contacts
+  - ui-gating
+related_workflows:
+  - contact-creation
+source_pr: medic/cht-core#8738
+source_sha: 91c9349205324af36106749fe6d60042dbceb8f0
+distilled_at: '2026-06-23'
+reviewed_by: null
+reviewed_at: null
+confidence: medium
+entities:
+  - webapp/src/ts/services/fast-action-button.service.ts
+  - webapp/src/ts/components/actionbar/actionbar.component.html
+concepts:
+  - permission-based UI gating
+  - authorization
+  - fast action button
+  - actionbar
+  - role-based access control
+related_issues:
+  - cht-core-8181
+stale: true
+---
+
+## Problem
+
+In the contacts FAB, `FastActionButtonService.getContactFormActions()` gated every child contact type on `can_create_places` (together with `can_edit`), whether the type was a person or a place. Only the contact-detail FAB lists person types (webapp/src/ts/modules/contacts/contacts-content.component.ts feeds it `getChildren(selectedContact.type.id)` without the `person` filter that the contacts list applies; like the list, it then keeps only the types whose create form the user can access), so a user granted `can_create_people` but not `can_create_places` lost the create-person actions there: the issue reports users unable to enroll patients after upgrading to 4.4.1, with granting `can_create_places` as the workaround. The contacts-list (left) pane of the old actionbar, which at this PR non-admin users with `can_view_old_action_bar` saw (the old actionbar and that permission were removed on master by PR #9361), listed place types only (`getChildren()` in webapp/src/ts/modules/contacts/contacts.component.ts drops `person` types); its create links required `can_edit` and `can_create_places`, and the container that holds them and the Export link required `can_create_places`, so users without that permission also lost the Export link. Conversely, a user with `can_create_places` but not `can_create_people` was offered person creation in the FAB. The old actionbar's contact-detail (right-pane) create actions were not affected; they already took a per-type `can_create_people`/`can_create_places` permission from webapp/src/ts/modules/contacts/contacts-content.component.ts.
+
+## Root Cause
+
+In `FastActionButtonService.getContactFormActions()` (`webapp/src/ts/services/fast-action-button.service.ts`), each child contact type's `canDisplay` called `this.authService.has(['can_edit', 'can_create_places'])`, with no branch on the contact type. In the old actionbar's contacts-tab left pane (`webapp/src/ts/components/actionbar/actionbar.component.html`), the create container was gated by `[mmAuthAny]="[ actionBar?.left?.childPlaces && 'can_create_places' ]"` and each create link or menu by `mmAuth="can_edit,can_create_places"`; the template did not mention `can_create_people` at all. That pane listed place types only (`getChildren()` in webapp/src/ts/modules/contacts/contacts.component.ts filters out `person` types), so this gating hid no person action; it hid the whole container, Export link included, from users without `can_create_places`.
+
+## Solution
+
+The PR corrected the existing checks rather than adding new ones.
+
+- FAB: `canDisplay` now requires `can_edit` plus `contactType.person ? 'can_create_people' : 'can_create_places'`, so each child contact type is gated by the permission for its kind. `getContactFormActions()` feeds both `getContactLeftSideActions()` and `getContactRightSideActions()`.
+- Actionbar: each create link or menu changed from `mmAuth="can_edit,can_create_places"` to `mmAuth="can_edit" [mmAuthAny]="['can_create_places', 'can_create_people']"`, so either permission is enough; this template does not split the check per contact type. The container, which also holds the Export link, changed to `[mmAuthAny]="[ 'can_export_all', 'can_export_contacts', 'can_create_places', 'can_create_people' ]"`.
+
+The same diff also changed the FAB label fallbacks from `||` to `??` and the send-message callback to `callbackOpenSendMessage?.(...)`.
+
+## Code Patterns
+
+Choose the permission from the contact type: in a FastAction's `canDisplay`, call `this.authService.has(['can_edit', contactType.person ? 'can_create_people' : 'can_create_places'])`. In templates, `mmAuth` takes a comma-separated list that must all be held, and `[mmAuthAny]` takes a list of which at least one must be held; on the same element both must pass.
+
+## Design Choices
+
+`can_edit` stays a hard requirement for every create action; only the second permission varies. The FAB checks per contact type. The old actionbar's create links only widened the gate to accept either permission.
+
+## Related Files
+
+- webapp/src/ts/services/fast-action-button.service.ts
+- webapp/src/ts/components/actionbar/actionbar.component.html (present at this PR's anchor; removed on master by PR #9361, "remove old action bar, search and filters")
+- webapp/tests/karma/ts/services/fast-action-button.service.spec.ts
+- tests/e2e/default/contacts/fab-actionbar.wdio-spec.js (added; removed on master by PR #9361)
+- tests/page-objects/default/common/common.wdio.page.js
+
+## Testing
+
+The Karma spec `webapp/tests/karma/ts/services/fast-action-button.service.spec.ts` adds a `person: true` child contact type to the `getContactRightSideActions()` cases and asserts that `authService.has` is called with `['can_edit', 'can_create_people']` for it, next to the existing `['can_edit', 'can_create_places']` calls for place types. The new e2e spec `tests/e2e/default/contacts/fab-actionbar.wdio-spec.js` checks that the FAB offers "New household" and "New person" under the default permissions, only the household form when `can_create_people` is removed, and only the person form when `can_create_places` is removed. It also checks the old action bar's contact-detail (right-pane) labels, with `can_view_old_action_bar` granted, under the same permission removals. The page object `tests/page-objects/default/common/common.wdio.page.js` gained `getFastActionItemsLabels()` and `getActionBarLabels()`. On master the e2e spec and `getActionBarLabels()` are gone, both removed by PR #9361; `getFastActionItemsLabels()` remains.
+
+## Related Issues
+
+- #8730: "Actionbar does not include links to create people when users have only the can_create_people permission" (this draft's issue)
+- #8181: "Remove old design that was replaced by Material design" — its PR #9361 later deleted the old actionbar template and this PR's e2e spec; the FAB check survives on master
+
+## Domain Rationale
+
+**Fit:** strong
+
+Apart from two small changes in the FAB service (the label fallbacks and an optional call), every source change in the diff is to a permission predicate: the arguments to `authService.has()` in `canDisplay`, and the `mmAuth`/`mmAuthAny` attributes in the actionbar template. The bug was a wrong mapping from action to permission. In the FAB the fix makes `can_create_people` and `can_create_places` each gate the create actions they name; in the old actionbar it widens the create links to accept either. The contacts page is only where these checks are shown; no contact-creation logic, form, or data handling changed.
diff --git a/agent-memory/domains/authentication/issues/8776-fix8096-block-admins-from-updating-own-password.md b/agent-memory/domains/authentication/issues/8776-fix8096-block-admins-from-updating-own-password.md
new file mode 100644
index 00000000..0333d4bd
--- /dev/null
+++ b/agent-memory/domains/authentication/issues/8776-fix8096-block-admins-from-updating-own-password.md
@@ -0,0 +1,100 @@
+---
+id: cht-core-8096
+category: bug
+domain: authentication
+domainFit: strong
+issueNumber: 8096
+issueUrl: https://github.com/medic/cht-core/issues/8096
+title: Block password updates for CouchDB server-admin users in the users API and hide the webapp update-password link for admins
+lastUpdated: '2026-09-29'
+summary: Before this PR, changing a CouchDB server admin's password from the webapp's user settings rewrote the admin entry in CouchDB config (`updateAdminPassword`) but left the deployment's `COUCHDB_PASSWORD` environment variable on the old value, so the CHT instance stopped working and the UI showed a misleading incorrect-password error. The fix deletes that admin-password path, makes user-management reject any password update for a user listed in CouchDB's `admins` config with a 400 (`Admin passwords must be changed manually in the database`), and hides the webapp's update-password link for `_admin` users.
+services:
+  - api
+  - webapp
+techStack:
+  - javascript
+  - typescript
+  - angular
+  - nodejs
+  - couchdb
+tags:
+  - password
+  - admin-user
+  - user-management
+  - credentials
+  - couchdb-admin
+  - security
+related_workflows:
+  - user-registration
+source_pr: medic/cht-core#8776
+source_sha: 15f96b2a650e4edeb44defae31298473190287cf
+distilled_at: '2026-06-23'
+reviewed_by: null
+reviewed_at: null
+confidence: medium
+entities:
+  - api/src/controllers/users.js
+  - shared-libs/user-management/src/users.js
+  - shared-libs/settings/src/index.js
+  - webapp/src/ts/modules/configuration-user/configuration-user.component.ts
+  - webapp/src/ts/modules/configuration-user/configuration-user.component.html
+concepts:
+  - password management
+  - CouchDB server admin vs _users-database user
+  - user credential update flow
+  - CouchDB-admin password-update guard
+  - user settings UI
+related_issues:
+  - cht-core-6986
+stale: false
+---
+
+## Problem
+
+Changing the password of a CouchDB server admin (for example the `medic` user of a CHT Docker deployment) through the webapp's user settings was reported as a failure but had in fact been applied, and it broke the instance: CouchDB accepted the new password while the `COUCHDB_PASSWORD` environment variable the CHT containers are configured with still held the old one, so the services failed until an operator updated the variable and restarted the containers. The error the UI showed was "Password is not correct.", for a change CouchDB had already accepted.
+
+## Root Cause
+
+At this PR's parent, `saveUserUpdates()` in shared-libs/user-management/src/users.js (logic added for #6986 by PR #7410) saved the `_users` doc and then, when the update carried a password and `isDbAdmin(user)` found the name in CouchDB's `admins` config, called `couchSettings.updateAdminPassword()` (shared-libs/settings/src/index.js). That helper pbkdf2-hashed the password and PUT it to `_node/<node>/_config/admins/<name>` on every cluster node. Nothing could update the container environment's `COUCHDB_PASSWORD`, so the credentials the deployment runs on diverged from CouchDB's.
+
+## Solution
+
+Removed the admin-password path instead of repairing it: `updateAdminPassword`, `getPasswordHash` and `getCouchNodes` were deleted from shared-libs/settings/src/index.js, and `saveUserUpdates()` now throws `error400('Admin passwords must be changed manually in the database')` before writing anything when the update carries a password and `isDbAdmin(user)` is true. `saveUserUpdates()` backs both `updateUser()` and `resetPassword()`, so any password change or reset for a CouchDB-config admin through user-management is rejected with a 400, whoever requests it — not only an admin changing their own. In the webapp, `ConfigurationUserComponent` (webapp/src/ts/modules/configuration-user/configuration-user.component.ts) replaced its `user` field with `canUpdatePassword = !user.token_login && !this.sessionService.isAdmin()` (`SessionService.isAdmin()` checks for the `_admin` role), and webapp/src/ts/modules/configuration-user/configuration-user.component.html shows the update-password link only when `canUpdatePassword` is true. The api/src/controllers/users.js change only reformats an error message and a log line.
+
+## Code Patterns
+
+Validate before writing: the guard in `saveUserUpdates()` now runs before `db.users.put(user)`, so a rejected admin password change leaves the `_users` doc untouched (previously the doc was saved first and the CouchDB-config write followed). Admin status is read from CouchDB config on the server (`couchSettings` `.getCouchConfig('admins')` inside `isDbAdmin`) and from the `_admin` role in the webapp (`SessionService.isAdmin()`); the UI hides the link and the API still enforces the rule. On master `isDbAdmin` takes the username (`isDbAdmin(user.name)`, since PR #9731), and `canUpdatePassword` also excludes `user.oidc_login` (since PR #9955).
+
+## Design Choices
+
+Block the operation rather than keep writing admin passwords into CouchDB config: a deployment's admin credentials also live in the container environment (`COUCHDB_PASSWORD`), which CHT cannot update at runtime, so changing only CouchDB's copy bricks the install. The restriction is enforced server-side (a 400 from user-management) and mirrored in the webapp by hiding the update-password link. The PR discussion leaves the door open to re-enabling admin password changes if the container environment variable can one day be updated as well.
+
+## Related Files
+
+- api/src/controllers/users.js
+- shared-libs/settings/src/index.js
+- shared-libs/settings/test/index.spec.js
+- shared-libs/user-management/src/users.js
+- shared-libs/user-management/test/unit/users.spec.js
+- webapp/src/ts/modules/configuration-user/configuration-user.component.ts
+- webapp/src/ts/modules/configuration-user/configuration-user.component.html
+- tests/e2e/upgrade/admin-user.wdio-spec.js
+- tests/integration/api/controllers/users.spec.js
+- tests/page-objects/default/common/common.wdio.page.js
+- tests/page-objects/default/users/user-settings.wdio.page.js
+- tests/utils/index.js
+
+## Testing
+
+Removed the `updateAdminPassword` unit tests from shared-libs/settings/test/index.spec.js. In shared-libs/user-management/test/unit/users.spec.js the admin cases now expect the `Admin passwords must be changed manually in the database` error (`should throw when trying to update admin password - #8096`, `should throw for admin user`). The integration test that changed an admin's password through `/api/v1/users/<name>` and logged in with it was removed from tests/integration/api/controllers/users.spec.js, and the e2e upgrade spec (tests/e2e/upgrade/admin-user.wdio-spec.js) no longer changes the admin password before logging in. Page objects were adjusted: tests/page-objects/default/common/common.wdio.page.js dropped its wait for the update-password key icon and gained `openEditProfile()`, which tests/page-objects/default/users/user-settings.wdio.page.js now uses; tests/utils/index.js gained debug logging of responses.
+
+## Related Issues
+
+- #8096: "Admin password change breaks CHT, shows wrong error message" — the issue this PR closes
+- #6986: "Changing admin password via webapp doesn't work" — the earlier bug whose fix (PR #7410) added the `updateAdminPassword` path this PR removes
+
+## Domain Rationale
+
+**Fit:** strong
+
+The PR governs password/credential management and distinguishes CouchDB admin accounts from regular users — credential handling and account-privilege checks are core authentication concerns, not the 'configuration-user' UI module they happen to live in.
diff --git a/agent-memory/domains/authentication/issues/8857-feat8338-use-pouchdb-session-plugin-in-api-sentinel-and-e2e-.md b/agent-memory/domains/authentication/issues/8857-feat8338-use-pouchdb-session-plugin-in-api-sentinel-and-e2e-.md
new file mode 100644
index 00000000..fffaa953
--- /dev/null
+++ b/agent-memory/domains/authentication/issues/8857-feat8338-use-pouchdb-session-plugin-in-api-sentinel-and-e2e-.md
@@ -0,0 +1,107 @@
+---
+id: cht-core-8338
+category: improvement
+domain: authentication
+domainFit: strong
+issueNumber: 8338
+issueUrl: https://github.com/medic/cht-core/issues/8338
+title: Use PouchDB session plugin for cookie/session-based CouchDB authentication in api, sentinel, and e2e tests
+lastUpdated: '2026-10-05'
+summary: The PouchDB clients in api and sentinel authenticated to CouchDB with HTTP Basic auth, so CouchDB ran PBKDF2 over the password on every request — a cost that grows with the iteration count that medic/cht-core#8338 set out to raise from 10. This registers the `pouchdb-session-authentication` plugin on those PouchDB constructors and on the ones in test utilities and scripts, so each client obtains a CouchDB session cookie and sends it on later requests instead of re-sending credentials. As of master the plugin is no longer registered anywhere; the PouchDB 9 upgrade (medic/cht-core#9988, 2025-06-03) removed it.
+services:
+  - api
+  - sentinel
+techStack:
+  - pouchdb
+  - couchdb
+  - nodejs
+  - javascript
+tags:
+  - session-authentication
+  - cookie-auth
+  - pouchdb-session-plugin
+  - couchdb-auth
+  - performance
+related_workflows: []
+source_pr: medic/cht-core#8857
+source_prs:
+  - "medic/cht-core#8857"
+  - "medic/cht-core#9030"
+source_sha: 61cf2bad3ee9c0ef2bda2b9d648970dbffad7d4c
+distilled_at: '2026-06-23'
+reviewed_by: null
+reviewed_at: null
+confidence: medium
+entities:
+  - api/src/db.js
+  - sentinel/src/db.js
+  - tests/utils/index.js
+  - api/tests/integration/migrations/utils.js
+  - scripts/get_users_meta_docs.js
+  - scripts/conflicts/auto-resolve.js
+  - scripts/conflicts/diff.js
+  - tests/scalability/replicate-real-world-docs/add-docs-to-remote.js
+concepts:
+  - session-based authentication
+  - cookie authentication (AuthSession)
+  - PouchDB plugin architecture
+  - CouchDB credential hashing (PBKDF2) cost
+  - database connection authentication
+related_issues:
+  - cht-core-9102
+  - cht-core-9534
+stale: true
+---
+
+## Problem
+
+The PouchDB clients in api and sentinel (plus several e2e, scalability and migration test utilities and maintenance scripts) connected to CouchDB using HTTP basic authentication, sending username/password on every request. CouchDB validates basic-auth credentials by running PBKDF2 password hashing on each request, adding CPU/latency overhead to every database operation made by these clients — overhead that would grow in proportion if the PBKDF2 iteration count were raised, which is what issue #8338 ("Research increasing pbkdf2 iterations") asks for.
+
+## Root Cause
+
+The PouchDB clients in api/src/db.js and sentinel/src/db.js (and shared test utilities) used basic auth with no session/cookie mechanism, so CouchDB re-hashed the credentials with PBKDF2 on every single request instead of authenticating once and reusing a session.
+
+## Solution
+
+Added the `pouchdb-session-authentication` package (`^1.1.0`) as a dependency in the existing api/package.json, sentinel/package.json and root package.json (plus their lockfiles) and registered it with `PouchDB.plugin(require('pouchdb-session-authentication'))`, immediately after `pouchdb-adapter-http`, in api/src/db.js and sentinel/src/db.js, in the test utilities tests/utils/index.js and api/tests/integration/migrations/utils.js, in scripts/get_users_meta_docs.js, scripts/conflicts/auto-resolve.js and scripts/conflicts/diff.js, and in tests/scalability/replicate-real-world-docs/add-docs-to-remote.js. No PouchDB constructor call changed: per the plugin's README it takes the credentials already present in the database URL (or an `auth` option), generates and stores a session cookie per user + CouchDB server pair, appends it as a `Cookie` header to outgoing requests, and regenerates the cookie and retries when it expires. Only PouchDB HTTP traffic is affected; requests the services made outside PouchDB at this PR's anchor (for example with `request-promise-native`) were not changed. (On master api and sentinel no longer use request-promise-native: api/src/db.js and sentinel/src/db.js switched to `@medic/couch-request` in PR #8833, `2402acdf9`, 2024-04-23; that library wrapped request-promise-native until PR #9746, `2c5a640c5`, 2025-01-27, rebuilt it on `fetch`.)
+
+On master none of this remains: the dependency moved from api/ and sentinel/package.json to the root package.json in the #9106 dependency consolidation (`918d8e1b4`), and the PouchDB 9 upgrade (PR #9988, `d6db604c7`, 2025-06-03) then removed it from package.json together with every `PouchDB.plugin(require('pouchdb-session-authentication'))` registration listed above. The package now appears in the root package-lock.json only as a dependency of the `cht-conf` dev dependency.
+
+## Code Patterns
+
+Register the plugin with `PouchDB.plugin(require('pouchdb-session-authentication'))` after `pouchdb-adapter-http` (the plugin's README requires that order) and leave the constructors alone — clients that already pass credentials in the database URL switch to cookie auth without further changes. Apply the identical one-line registration to every PouchDB constructor that talks to CouchDB: service db modules (api/src/db.js, sentinel/src/db.js) and shared test/script utilities (tests/utils/index.js). (As of this PR; on master no code registers the plugin — see Solution.)
+
+## Design Choices
+
+Cookie/session auth trades a small one-time login for much cheaper subsequent requests, versus basic auth that re-hashes credentials every request; using an off-the-shelf PouchDB session plugin avoids hand-rolling cookie handling and keeps the change to one registration line per client. The driver is security rather than speed: issue #8338 notes CHT's password hashing used only 10 PBKDF2 iterations, and raising that count makes every Basic-auth request proportionally more expensive, so the high-volume service clients move to session cookies first (the plugin's README cites CouchDB's advice to use session cookies with high iteration counts).
+
+## Related Files
+
+- api/src/db.js
+- sentinel/src/db.js
+- api/package.json
+- sentinel/package.json
+- package.json
+- api/tests/integration/migrations/utils.js
+- tests/utils/index.js
+- scripts/conflicts/auto-resolve.js (present at this PR's anchor; removed on master by the old-scripts cleanup, PR #10207)
+- scripts/conflicts/diff.js (present at this PR's anchor; removed on master by the old-scripts cleanup, PR #10207)
+- scripts/get_users_meta_docs.js
+- tests/scalability/replicate-real-world-docs/add-docs-to-remote.js
+
+## Testing
+
+No new dedicated unit tests; the change updates shared e2e (tests/utils/index.js), integration migration (api/tests/integration/migrations/utils.js), and scalability test utilities to use the same session plugin, so existing e2e/integration/scalability suites exercise the new cookie-based auth path end to end.
+
+## Related Issues
+
+- #8338: "Research increasing pbkdf2 iterations" — the issue this PR references; moving service clients off per-request Basic auth is the prerequisite for raising the iteration count
+- #9102: "Add PouchDb session plugin cht-core" — this PR's own tracking issue (Type: Technical issue), opened and closed on 2024-05-08, after the PR merged on 2024-04-18
+- #9534: "Upgrade to latest version of PouchDB (current adapter)" — its PR #9988 removed the `pouchdb-session-authentication` registrations this PR added
+- PR #9030: "chore(#8338): use CouchDb session in e2e tests requests" — follow-up for the same issue that made the `request()` helper in tests/utils/index.js POST to `/_session` once and reuse the `AuthSession` cookie instead of sending Basic auth; on master that helper sends an `Authorization: Basic` header again (`setRequestAuth`, since PR #9703 removed request-promise-native from the e2e tests)
+
+## Domain Rationale
+
+**Fit:** strong
+
+The PR replaces basic-auth (which forces CouchDB to re-hash credentials on every request) with cookie/session-based authentication via a PouchDB session plugin for api's and sentinel's PouchDB connections to CouchDB, to make stronger password hashing affordable; the authentication mechanism and session management are the entire substance of the change. It is application code (api/src/db.js, sentinel/src/db.js), not CI/build/deploy lifecycle, so it is not infrastructure.
diff --git a/agent-memory/domains/authentication/issues/8924-fix8868-dont-forward-all-headers-for-get-requests.md b/agent-memory/domains/authentication/issues/8924-fix8868-dont-forward-all-headers-for-get-requests.md
new file mode 100644
index 00000000..5e5598c7
--- /dev/null
+++ b/agent-memory/domains/authentication/issues/8924-fix8868-dont-forward-all-headers-for-get-requests.md
@@ -0,0 +1,97 @@
+---
+id: cht-core-8868
+category: bug
+domain: authentication
+domainFit: strong
+issueNumber: 8868
+issueUrl: https://github.com/medic/cht-core/issues/8868
+title: Stop forwarding content-length header on GET /_session authentication request to prevent HAProxy request truncation under keep-alive
+lastUpdated: '2026-10-05'
+summary: Authenticating a user forwarded all original request headers (including content-length from POSTs) to a GET /_session request, which under the keep-alive default that Node 19 introduced (the api ran Node 20 from the 4.6.0 line) caused HAProxy to truncate the next request on the reused connection and return 400 errors. The fix stops forwarding the content-length header on the session request. It reached users in 4.6.0 through the 4.6.x backport medic/cht-core#8933 (first tagged 4.6.0-beta.3) and in 4.7.0 from master.
+services:
+  - api
+techStack:
+  - javascript
+  - nodejs
+  - couchdb
+  - haproxy
+  - http
+  - docker
+  - mocha
+tags:
+  - http-headers
+  - content-length
+  - keep-alive
+  - session-authentication
+  - haproxy
+  - node-20
+  - connection-reuse
+  - reverse-proxy
+  - request-truncation
+related_workflows: []
+source_pr: medic/cht-core#8924
+source_prs:
+  - "medic/cht-core#8924"
+  - "medic/cht-core#8933"
+source_sha: 831bd6e8a65900a95126a3224f9ebb5ef9968180
+distilled_at: '2026-06-23'
+reviewed_by: null
+reviewed_at: null
+confidence: medium
+entities:
+  - api/src/auth.js
+  - tests/integration/haproxy/keep-alive.spec.js
+concepts:
+  - session authentication via GET /_session
+  - HTTP header forwarding/proxying
+  - HTTP keep-alive persistent connections
+  - content-length and connection reuse
+  - reverse proxy (HAProxy) request framing
+related_issues: []
+stale: false
+---
+
+## Problem
+
+When authenticating a user, the API copied all headers from the original request onto a GET /_session request sent to CouchDB. If the original request was a POST carrying a content-length header, that header was forwarded onto the bodyless GET. Under Node 20 (the 4.6.0 line moved the api image from Node 16 to Node 20 in PR #8824 for #7993, and Node 19 had made outgoing HTTP keep-alive the default), api's connection to HAProxy was reused, and HAProxy, treating the bodyless GET as unfinished, consumed content-length characters of the following request on that connection, producing an invalid request and a 400 status code. It was observed only when hitting API directly or via the AWS load balancer, never through nginx. Issue #8868 reported it after upgrading to 4.6.0-beta.2: users could not log in to the webapp and authenticated REST API calls failed with 400.
+
+## Root Cause
+
+In api/src/auth.js, the code that builds the GET /_session authentication request indiscriminately forwarded all of the user's original request headers (to avoid having to enumerate every auth mechanism such as cookie/authorization). For a GET with no body, the forwarded content-length is semantically wrong, and combined with keep-alive connection reuse it caused the downstream proxy to mis-frame subsequent requests on the same connection.
+
+## Solution
+
+Modified the private `get` helper in api/src/auth.js (`const get = (path, headers) =>`), which `getUserCtx(req)` calls as `get('/_session', req.headers)`: it now copies the headers and deletes every key matching `contentLengthRegex = /^content-length$/i` (any casing) before the request, while still passing through the auth-bearing headers (cookie, authorization, etc.). Backported to the 4.6.x release branch as PR #8933 (`30530e89f`, cherry-picked from the master commit `831bd6e8a` with an identical patch); 4.6.0 was the first release to include it, and the master commit first shipped in 4.7.0.
+
+On master `get()` also strips `content-type` (`contentTypeRegex = /^content-type$/i`, added by PR #9746, which replaced request-promise-native with fetch) and sends the request through `@medic/couch-request`, so the header denylist is now two names.
+
+## Code Patterns
+
+When proxying/forwarding headers from one request to a derived request, strip headers that do not apply to the new request's method/body — notably remove content-length for bodyless GET requests to avoid corrupting connection framing under keep-alive, and match header names case-insensitively (`/^content-length$/i`; the unit test checks five casings). See `get()` in api/src/auth.js.
+
+## Design Choices
+
+Rather than switching to an allowlist of only the auth headers needed for /_session (which would require knowing every supported authentication method), the fix keeps the existing forward-everything approach but blocks the single problematic header (content-length; on master `content-type` is blocked too). This preserves support for arbitrary auth mechanisms while removing the one header that breaks keep-alive connection reuse.
+
+## Related Files
+
+- api/src/auth.js
+- api/tests/mocha/auth.spec.js
+- tests/integration/haproxy/keep-alive.spec.js
+- tests/integration/haproxy/keep-alive-script/Dockerfile
+- tests/integration/haproxy/keep-alive-script/cmd.sh
+- tests/integration/haproxy/keep-alive-script/docker-compose.yml
+
+## Testing
+
+Unit tests in api/tests/mocha/auth.spec.js gained a `getUserCtx` block, including `should clean content-length headers before forwarding`, which sets `content-length`, `Content-Length`, `Content-length`, `content-Length` and `CONTENT-LENGTH` on the request and asserts none reaches the `/_session` GET. A new integration test tests/integration/haproxy/keep-alive.spec.js runs a small docker-compose service (tests/integration/haproxy/keep-alive-script/: Dockerfile, cmd.sh, docker-compose.yml) on the e2e network and asserts its output contains no `HTTP/1.1 400 Bad Request` but does contain `HTTP/1.1 302 Found`, `Connection: keep-alive`, `Set-Cookie: AuthSession=` and `Set-Cookie: userCtx=`. The service's tests/integration/haproxy/keep-alive-script/cmd.sh curls a JSON login POST to `'http://api:5988/medic/login'` straight to api, bypassing nginx.
+
+## Related Issues
+
+- #8868: "Session requests failing after upgrade" — the issue both PRs fix; requests truncated and returning 400 because content-length was forwarded onto the GET /_session auth request under the keep-alive default that Node 19 introduced (the api ran Node 20 from the 4.6.0 line)
+
+## Domain Rationale
+
+**Fit:** strong
+
+The fix lives in api/src/auth.js and changes how the user session-authentication request (GET /_session) forwards headers, so it squarely belongs to authentication. The haproxy/keep-alive symptom is only where the transport bug surfaces; in-application auth code stays in its functional domain rather than being pushed into infrastructure just because HAProxy is involved.
diff --git a/agent-memory/domains/authentication/issues/8928-feat8877-look-up-users-from-their-facilityid-or-contactid.md b/agent-memory/domains/authentication/issues/8928-feat8877-look-up-users-from-their-facilityid-or-contactid.md
new file mode 100644
index 00000000..15ed1f01
--- /dev/null
+++ b/agent-memory/domains/authentication/issues/8928-feat8877-look-up-users-from-their-facilityid-or-contactid.md
@@ -0,0 +1,97 @@
+---
+id: cht-core-8877
+category: feature
+domain: authentication
+domainFit: strong
+issueNumber: 8877
+issueUrl: https://github.com/medic/cht-core/issues/8877
+title: Extend GET /api/v2/users to look up users by facility_id and/or contact_id
+lastUpdated: '2026-10-05'
+summary: There was no way to query the users API to find which users are linked to a given facility or contact. This PR extends `GET /api/v2/users` to accept `facility_id` and/or `contact_id` query parameters (gated behind `can_view_users`), backed by a new `_users` db view and a migration that backfills `contact_id` onto existing user docs.
+services:
+  - api
+techStack:
+  - javascript
+  - nodejs
+  - couchdb
+tags:
+  - user-management
+  - users-api
+  - couchdb-view
+  - migration
+  - facility-lookup
+  - contact-lookup
+  - permissions
+related_workflows:
+  - data-migration
+source_pr: medic/cht-core#8928
+source_sha: 5e9032d87a10e268b052aa5279e9b88995b3a090
+distilled_at: '2026-06-23'
+reviewed_by: null
+reviewed_at: null
+confidence: medium
+entities:
+  - api/src/controllers/users.js
+  - shared-libs/user-management/src/users.js
+  - shared-libs/user-management/src/libs/facility.js
+  - api/src/migrations/add-contact-id-to-user-docs.js
+  - ddocs/users-db/users/views/users_by_field/map.js
+concepts:
+  - permission-gated API endpoint (can_view_users)
+  - indexed CouchDB map view for user lookup
+  - user docs in the _users database
+  - idempotent backfill migration
+  - query-parameter-based filtering on an existing route
+related_issues:
+  - cht-core-8986
+stale: true
+---
+
+## Problem
+
+The `GET /api/v2/users` route could not be filtered, so there was no efficient, supported way to find which users are associated with a particular facility (`facility_id`) or contact (`contact_id`). User management also did not write `contact_id` onto `_users` docs — it lived only on the `user-settings` doc in the medic db — so there was nothing to index for a contact lookup.
+
+## Root Cause
+
+The users API exposed no filtering mechanism for `facility_id`/`contact_id`, there was no view in the `_users` db indexing users by those fields, and existing user docs lacked a `contact_id` field to index against.
+
+## Solution
+
+Extended `GET /api/v2/users` (controller in api/src/controllers/users.js) to accept `facility_id` and/or `contact_id` query parameters and return the matching users, reusing the existing `can_view_users` permission gate. Added a `users_by_field` map view (ddocs/users-db/users/views/users_by_field/map.js) to index users by these fields, added the query logic in shared-libs/user-management/src/users.js (`getUsers` queries `users/users_by_field`; `getUsersAndSettings` then fetches the matching settings docs by id), made user create/update also write `contact_id` onto the `_users` doc (`getUserUpdates`), changed shared-libs/user-management/src/libs/facility.js `list()` to read `facility_id` and `contact_id` from the user docs, registered the new `_design/users` ddoc (`jsonFileName: 'users.json'` in api/src/services/setup/databases.js) for the users db in setup/databases, and added the `add-contact-id-to-user-docs` migration to backfill `contact_id` onto existing user docs so they are indexable.
+
+## Code Patterns
+
+CouchDB view `ddocs/users-db/users/views/users_by_field/map.js` emits user fields (facility_id, contact_id) as view keys for indexed lookup, queried from shared-libs/user-management/src/users.js (`getUsers`) — the api controller only passes `req.query.facility_id`/`contact_id` through as filters. Idempotent backfill migration pattern in api/src/migrations/add-contact-id-to-user-docs.js populates a new field onto existing `_users` docs. New ddoc/view bundled via scripts/build/ddoc-compile.js.
+
+## Design Choices
+
+Reused the existing `GET /api/v2/users` route and `can_view_users` permission instead of adding a new endpoint, keeping the API surface and authorization model consistent. Backfilling `contact_id` via a migration (rather than computing it at read time) allows the lookup to be served by a single indexed view.
+
+## Related Files
+
+- api/src/controllers/users.js
+- api/src/migrations/add-contact-id-to-user-docs.js (added)
+- api/src/services/setup/databases.js
+- api/tests/integration/migrations/utils.js (this PR's `db.users` test-db swap was removed on master by PR #9455)
+- ddocs/users-db/users/_id (added)
+- ddocs/users-db/users/views/users_by_field/map.js (added)
+- scripts/build/ddoc-compile.js
+- shared-libs/user-management/src/libs/facility.js
+- shared-libs/user-management/src/users.js
+- tests/integration/api/controllers/users.spec.js
+
+## Testing
+
+Added a mocha unit spec for the migration (api/tests/mocha/migrations/add-contact-id-to-user-docs.spec.js, new) and updated the existing specs for the controller (api/tests/mocha/controllers/users.spec.js), setup/databases and utils, and shared-libs/user-management (shared-libs/user-management/test/unit/users.spec.js, shared-libs/user-management/test/unit/libs/facility.spec.js). Added an integration test for the migration (api/tests/integration/migrations/add-contact-id-to-user-docs.js, new at this PR; removed on master by #10187, `chore(#9639): remove old migrations [5.0]`, though the migration and its mocha spec remain) and updated the users API route integration test (tests/integration/api/controllers/users.spec.js).
+
+## Related Issues
+
+- #8877: "/api/v2/users look up users by `facility_id` and/or `contact_id`" — this draft's issue
+- #8986: "/api/v2/users look up data for single user" — split off from #8877; shipped as `GET /api/v2/users/:username` by PR #9016
+- PR medic/cht-docs#1318: "feat: Document looking up users from their `facility_id` or `contact_id`" — documents the new query parameters
+
+## Domain Rationale
+
+**Fit:** strong
+
+The PR extends user management — the `GET /api/v2/users` route, the `_users` database views/docs, and access gated behind the `can_view_users` permission — which is canonically the authentication domain. The lookup keys (facility_id/contact_id) reference contacts, but the entities being queried, managed, and returned are users, so this is not contacts.
diff --git a/agent-memory/domains/authentication/issues/9016-feat8986-add-api-for-getting-single-user.md b/agent-memory/domains/authentication/issues/9016-feat8986-add-api-for-getting-single-user.md
new file mode 100644
index 00000000..d90abdd1
--- /dev/null
+++ b/agent-memory/domains/authentication/issues/9016-feat8986-add-api-for-getting-single-user.md
@@ -0,0 +1,92 @@
+---
+id: cht-core-8986
+category: feature
+domain: authentication
+domainFit: strong
+issueNumber: 8986
+issueUrl: https://github.com/medic/cht-core/issues/8986
+title: Add GET /api/v2/users/:username endpoint to fetch a single user
+lastUpdated: '2026-10-05'
+summary: The API could only list all users, with no way to retrieve one user by username. This PR adds a GET /api/v2/users/:username endpoint, open to holders of `can_view_users` or to the user fetching themselves, wired through the API controller/routing and a new single-user lookup (`getUser`) in the user-management shared library.
+services:
+  - api
+techStack:
+  - javascript
+  - nodejs
+  - express
+  - couchdb
+  - mocha
+tags:
+  - user-management
+  - api
+  - rest-api
+  - single-user
+  - users-endpoint
+  - v2-api
+related_workflows:
+  - user-registration
+source_pr: medic/cht-core#9016
+source_sha: db531e1e028054fc5146dd4816eb4594ae3ee5b9
+distilled_at: '2026-06-23'
+reviewed_by: null
+reviewed_at: null
+confidence: medium
+entities:
+  - api/src/controllers/users.js
+  - api/src/routing.js
+  - shared-libs/user-management/src/users.js
+concepts:
+  - REST API endpoint
+  - user management
+  - GET single resource by key
+  - shared-library delegation
+  - controller/routing separation
+related_issues:
+  - cht-core-8877
+stale: false
+---
+
+## Problem
+
+There was no API to retrieve data about an individual user; only the list-all-users endpoint (GET /api/v2/users) existed, so any consumer needing a single user's data had to fetch and filter the entire user list.
+
+## Root Cause
+
+The API exposed no route or controller handler for fetching an individual user by username, and the user-management shared library exported no function that returned a single user in the shape `getList`/`mapUsers` produce. Its existing by-name reads did not fill that gap: the private `getUserDoc`/`getUserDocsByName` returned the raw `_users` and user-settings docs, and the exported `getUserSettings({ name })` returned a merged, facility/contact-hydrated user-settings doc that the api authorization middleware used to populate `req.userCtx`.
+
+## Solution
+
+Registered a new GET /api/v2/users/:username route in api/src/routing.js, added a controller handler in api/src/controllers/users.js that resolves the username, and implemented the single-user retrieval logic in shared-libs/user-management/src/users.js, mirroring the existing list-users flow but keyed on a single username. The new handler takes the name `users.v2.get`; the list handlers it displaced were renamed `users.list` (v1) and `users.v2.list`. It allows the request when the requester has `can_view_users` or is fetching their own user (`isReferencingSelf`: session name equals the username and any Basic-auth username matches too), otherwise it returns 403 `Insufficient privileges`. `getUser(username)` reads the `_users` and `user-settings` docs, fetches the user's place and contact via `facility.list([user])`, and builds the result with `mapUser`, a helper extracted from `mapUsers`.
+
+## Code Patterns
+
+Controller (api/src/controllers/users.js) delegates business logic to the shared-libs/user-management/src/users.js library rather than reimplementing it; the route is declared in api/src/routing.js following the existing /api/v2/users registration pattern, extended with a :username path parameter for single-resource GET.
+
+## Design Choices
+
+Reused the existing user-management shared library instead of duplicating user-lookup logic in the controller, keeping a single source of truth shared across services; the endpoint follows REST conventions (GET /api/v2/users/{username}) so the single-user response shape stays consistent with entries returned by the list endpoint.
+
+## Related Files
+
+- api/src/controllers/users.js
+- api/src/routing.js
+- api/tests/mocha/controllers/users.spec.js
+- shared-libs/user-management/src/users.js
+- shared-libs/user-management/test/unit/users.spec.js
+- tests/integration/api/controllers/users.spec.js
+
+## Testing
+
+Added cases to the existing specs: the controller's `get single user` block (api/tests/mocha/controllers/users.spec.js — including self-access with and without Basic auth, refusal when not self, and conflicting Basic auth vs session cookie), the shared library's `getUser` block (shared-libs/user-management/test/unit/users.spec.js — missing username, missing `_users` or `user-settings` doc), and `GET api/v2/users/{username}` integration cases in tests/integration/api/controllers/users.spec.js (with and without `can_view_users`, self-retrieval, unknown user).
+
+## Related Issues
+
+- #8986: "/api/v2/users look up data for single user" — this draft's issue
+- #8877: "/api/v2/users look up users by `facility_id` and/or `contact_id`" — the issue #8986 was split off from; shipped by PR #8928
+- PR medic/cht-docs#1350: "feat: add API docs for getting user by username" — documents the new endpoint
+
+## Domain Rationale
+
+**Fit:** strong
+
+User management (users, their roles and facility associations) is canonically part of the authentication domain in CHT; this PR adds a user-retrieval API endpoint backed by the user-management shared library, and its access rule (`can_view_users` or the user themselves) is an authorization decision, so it is an auth-domain concern rather than an external-system integration.
diff --git a/agent-memory/domains/authentication/issues/9107-fix8886-block-users-from-editing-important-fields-in-their-s.md b/agent-memory/domains/authentication/issues/9107-fix8886-block-users-from-editing-important-fields-in-their-s.md
new file mode 100644
index 00000000..6b91d089
--- /dev/null
+++ b/agent-memory/domains/authentication/issues/9107-fix8886-block-users-from-editing-important-fields-in-their-s.md
@@ -0,0 +1,95 @@
+---
+id: cht-core-8886
+category: bug
+domain: authentication
+domainFit: strong
+issueNumber: 8886
+issueUrl: https://github.com/medic/cht-core/issues/8886
+title: Block non-admin users from creating user-settings docs or changing their roles via validate_doc_update
+lastUpdated: '2026-09-29'
+summary: Users could edit their own user-settings doc in the medic database, including the `roles` array that shadows their `_users` roles, through direct API calls or by replicating a PouchDB edit. The medic-client `validate_doc_update` now rejects, for anyone who is not a DB admin, creating a user-settings doc or changing its `roles`. The PR also fixes the medic ddoc's `isDbAdmin` check so that users made admins by role in the database security object are recognised.
+services:
+  - admin
+  - webapp
+techStack:
+  - javascript
+  - couchdb
+  - pouchdb
+  - angularjs
+tags:
+  - privilege-escalation
+  - validate_doc_update
+  - user-settings
+  - authorization
+  - permissions
+  - security
+  - couchdb-ddoc
+related_workflows:
+  - user-registration
+source_pr: medic/cht-core#9107
+source_sha: b0fa207225a408dccc2b13d922809c76bb28f6d9
+distilled_at: '2026-06-23'
+reviewed_by: null
+reviewed_at: null
+confidence: medium
+entities:
+  - ddocs/medic-db/medic/validate_doc_update.js
+  - ddocs/medic-db/medic-client/validate_doc_update.js
+  - admin/src/js/services/privacy-policies.js
+  - admin/src/js/controllers/display-privacy-policies-preview.js
+  - admin/src/js/main.js
+concepts:
+  - CouchDB validate_doc_update validation functions
+  - field-level write authorization
+  - privilege-escalation prevention
+  - user-settings document protection
+  - DB-admin bypass via the security object (secObj)
+related_issues: []
+stale: false
+---
+
+## Problem
+
+A user can write their own user-settings doc (`_id` `org.couchdb.user:<name>`, `type: 'user-settings'`) in the medic database, either through direct API calls or by editing it in PouchDB and letting it replicate. Its `roles` array shadows the authoritative `_users` doc. An edited copy can therefore drift from `_users`, mislead code that reads the medic copy, or let a malicious user rewrite their own roles shadow. The issue rated the severity low because the shadow roles are not authoritative on the server.
+
+## Root Cause
+
+Before this PR, the medic-client `validate_doc_update` checked only the structure of user-settings docs. `validateUserSettings()` checked the `_id` prefix and case, `name`, the type of `known`, and that `roles` exists, but nothing about who was writing. The medic ddoc's `checkAuthority()` did not look at user-settings at all. Separately, the medic ddoc's `isDbAdmin()` looped with `for (var i = 0; i < userCtx.roles; i++)`, missing `.length`, so the loop did not run for role names. Users who were admins by role in the database security object (`secObj.admins.roles`) were therefore not treated as DB admins.
+
+## Solution
+
+- `ddocs/medic-db/medic-client/validate_doc_update.js`: the function now takes `secObj` and adds two helpers, `hasRole` (`var hasRole = function(roles, role)`) and `isDbAdmin`. `isDbAdmin` is true for the `_admin` role, or for a name or role listed in `secObj.admins`, and DB admins return early before any other check. For `type === 'user-settings'`, `authorizeUserSettings()` now runs after `validateUserSettings()`. It throws `forbidden` with "You are not authorized to create user-settings" when there is no `oldDoc`. It throws "You are not authorized to edit roles" when `oldDoc.roles` is not an object, or when `newDoc.roles` differs from it in length or in any element by position. Only `roles` is compared; other fields, including `known` and `privacy_policy_acceptance_log`, stay writable by the user.
+- `ddocs/medic-db/medic/validate_doc_update.js`: `hasRole` now takes a roles array, and `isDbAdmin` loops with `i < userCtx.roles.length` over `secObj.admins.roles`.
+- Admin app: the PR deleted the `PrivacyPolicies` service (`admin/src/js/services/privacy-policies.js`) and its spec, and dropped its `require` from `admin/src/js/main.js`. Its `decodeUnicode` logic, the only part the admin app used, was inlined into `admin/src/js/controllers/display-privacy-policies-preview.js`.
+
+## Code Patterns
+
+Authority check inside `validate_doc_update`: return early for DB admins (`isDbAdmin(userCtx, secObj)`, which checks `_admin` and `secObj.admins.names`/`secObj.admins.roles`). Then compare `oldDoc` with `newDoc` on the protected field and `throw({ forbidden: msg })` (via `_err`) on any difference, and reject creation when `oldDoc` is absent. An array field is compared by length and then element by element.
+
+## Design Choices
+
+The rule is enforced in the database (`validate_doc_update`) rather than in application code, so it covers both routes the issue names: direct API/CouchDB writes and edits replicated up from PouchDB. CouchDB runs every design doc's `validate_doc_update` on each write to the medic database, so the check in `medic-client` applies on the server. That file's header comment reserves it for structure checks "irrespective of authority", yet the PR put the authority check there and added no user-settings check to the medic ddoc. The early `isDbAdmin()` return also exempts DB admins from medic-client's form `_id` and user-settings structure checks, which applied to them before.
+
+## Related Files
+
+- ddocs/medic-db/medic/validate_doc_update.js
+- ddocs/medic-db/medic-client/validate_doc_update.js
+- webapp/tests/mocha/unit/validate_doc_update.spec.js
+- admin/src/js/services/privacy-policies.js (deleted)
+- admin/src/js/controllers/display-privacy-policies-preview.js
+- admin/src/js/main.js
+- admin/tests/unit/services/privacy-policies.spec.js (deleted)
+
+## Testing
+
+`webapp/tests/mocha/unit/validate_doc_update.spec.js` (modified) loads both ddocs' validators. It groups the user-settings cases under `describe('type:user-settings')` and adds four cases: "does not allow non-admins to change roles", "allows admins to change roles", "allows everyone to update their own privacy policy acceptance", and "allows everyone to update their own known status". Existing tests were converted from `done` callbacks to synchronous functions, and "only db and national admins are allowed change their own place" became "only db admins are allowed change their own place". The admin `admin/tests/unit/services/privacy-policies.spec.js` was deleted along with the service.
+
+## Related Issues
+
+- #8886: "Block users from editing important fields in user settings docs" (this draft's issue)
+
+## Domain Rationale
+
+**Fit:** strong
+
+The PR adds an authorization rule: only DB admins may create user-settings docs or change their `roles`. It also fixes how the medic ddoc recognises DB admins by role. Both are roles and access-control logic. The CouchDB design doc is only where the rule is enforced, and no replication or sync behaviour changes.
diff --git a/agent-memory/domains/authentication/issues/9109-fix9108-block-updating-admin-only-docs.md b/agent-memory/domains/authentication/issues/9109-fix9108-block-updating-admin-only-docs.md
new file mode 100644
index 00000000..8b1c1492
--- /dev/null
+++ b/agent-memory/domains/authentication/issues/9109-fix9108-block-updating-admin-only-docs.md
@@ -0,0 +1,82 @@
+---
+id: cht-core-9108
+category: bug
+domain: authentication
+domainFit: strong
+issueNumber: 9108
+issueUrl: https://github.com/medic/cht-core/issues/9108
+title: Block non-admin users from updating admin-only docs by also checking oldDoc in validate_doc_update
+lastUpdated: '2026-09-29'
+summary: Non-admin users could modify admin-only docs because the medic ddoc's `validate_doc_update` classified only the incoming `newDoc`, so a write whose new revision no longer looked admin-only (for example a `form` doc saved with another `type`) passed. The fix also classifies `oldDoc` and rejects a non-admin write when either revision is admin-only.
+services:
+  - webapp
+techStack:
+  - javascript
+  - couchdb
+  - mocha
+tags:
+  - validate-doc-update
+  - access-control
+  - authorization
+  - admin-only-docs
+  - protected-docs
+  - couchdb-validation
+  - security
+related_workflows: []
+source_pr: medic/cht-core#9109
+source_sha: 2bebd76e75044fe677885284d13924e662a617a3
+distilled_at: '2026-06-23'
+reviewed_by: null
+reviewed_at: null
+confidence: medium
+entities:
+  - ddocs/medic-db/medic/validate_doc_update.js
+  - webapp/tests/mocha/unit/validate_doc_update.spec.js
+concepts:
+  - CouchDB validate_doc_update validation function
+  - Role-based access control / authorization
+  - Admin-only (protected) documents
+  - Server-side write validation during replication
+  - Defense against malicious offline replication
+related_issues: []
+stale: false
+---
+
+## Problem
+
+Non-admin users could modify admin-only docs. These are the documents the medic ddoc reserves for DB admins by `type` (`form`, `translations` and `token_login` as of this PR) or by `_id` (any `_design/` doc, plus `resources`, `service-worker-meta`, `zscore-charts`, `settings`, `branding`, `partners`, `privacy-policies` and `extension-libs`). On master the lists also include the `ui-extension` type, which arrived with the ui-extensions epic (PR #11050), and the `migration-log` id, added by PR #10187. The public issue withholds the details. The check applies to every user write that reaches CouchDB, whether made directly or replicated up from a device.
+
+## Root Cause
+
+Before this PR, `checkAuthority()` in `ddocs/medic-db/medic/validate_doc_update.js` already rejected non-admin writes to admin-only docs with "You are not authorized to edit admin only docs", but its condition was `if (isAdminOnlyDoc(newDoc)) {`, which tests the new revision alone. `isAdminOnlyDoc` matches on `_id` (the `_design/` prefix or `ADMIN_ONLY_IDS`) or on `type` (`ADMIN_ONLY_TYPES`). A non-admin could therefore overwrite a type-classified doc, such as a form or translations doc, by saving a revision with a different `type`, or delete one, because a deletion stub carries no `type`; the new tests cover the type swap (`type: 'feedback'`). Id-classified docs were already covered, because the new revision keeps the same `_id`.
+
+## Solution
+
+The guard became `if (isAdminOnlyDoc(newDoc) || (oldDoc && isAdminOnlyDoc(oldDoc)))`, so a non-admin write is rejected when either the stored revision or the incoming one is admin-only. DB admins still return early through `isDbAdmin()` before this check.
+
+## Code Patterns
+
+Authorization guard inside a CouchDB `validate_doc_update` function (`function(newDoc, oldDoc, userCtx, secObj)`): resolve admin status first (`isDbAdmin`, meaning the `_admin` role or a name or role in `secObj.admins`) and return early. Then classify both `newDoc` and `oldDoc` against the admin-only set, and `throw({ forbidden: msg })` (via `_err`) if either matches. Classifying only the incoming revision lets a writer escape the check by changing the field the classification keys on. See ddocs/medic-db/medic/validate_doc_update.js.
+
+## Design Choices
+
+The fix stays in the medic ddoc's `validate_doc_update`, which CouchDB runs on every write to the medic database. It closes the gap by classifying the stored revision as well as the incoming one. `oldDoc` is null when a doc is created, hence the `oldDoc &&` guard.
+
+## Related Files
+
+- ddocs/medic-db/medic/validate_doc_update.js
+- webapp/tests/mocha/unit/validate_doc_update.spec.js
+
+## Testing
+
+`webapp/tests/mocha/unit/validate_doc_update.spec.js` (modified). The existing creation cases, now under the describe "only db and national admins are allowed to create...", still assert that `_admin` is allowed and that the `national_admin` and `test` roles are forbidden. A new block, "only db and national admins are allowed to update...", covers two kinds of update: forms and translations docs rewritten as `type: 'feedback'`, and `extension-libs`, `branding` and `partners` docs given an extra field. Each case asserts that `_admin` is allowed and a `test`-role user is forbidden. Despite both describe names, no case expects `national_admin` to be allowed.
+
+## Related Issues
+
+- #9108: "Admin only docs can be modified by non-admin users" (this draft's issue)
+
+## Domain Rationale
+
+**Fit:** strong
+
+The PR changes who may write admin-only docs: it widens the authority check in the medic ddoc's `validate_doc_update` so that non-admins cannot modify them by changing the doc's `type`. That is role-based access control. CouchDB is only where the check is enforced.
diff --git a/agent-memory/domains/authentication/issues/9126-feat6543-adds-api-side-support-for-users-with-multiple-facil.md b/agent-memory/domains/authentication/issues/9126-feat6543-adds-api-side-support-for-users-with-multiple-facil.md
new file mode 100644
index 00000000..33fdad1d
--- /dev/null
+++ b/agent-memory/domains/authentication/issues/9126-feat6543-adds-api-side-support-for-users-with-multiple-facil.md
@@ -0,0 +1,120 @@
+---
+id: cht-core-6543
+category: feature
+domain: authentication
+domainFit: strong
+issueNumber: 6543
+issueUrl: https://github.com/medic/cht-core/issues/6543
+title: Support users with multiple facilities — v3 users API, authorization, and contact-list display
+lastUpdated: '2026-10-05'
+summary: 'CHT users could previously be associated with only a single facility (place). This adds multi-facility support in the API and webapp: a new /v3/users create endpoint (plus /v3/users/:username, which reuses the v1 update handler) taking an array of existing facility UUIDs, with more than one place allowed only when one of the user''s roles holds the new `can_have_multiple_places` permission; user-management library and authorization changes so a user''s doc download/upload permissions span all of their facilities (PR #9126); the webapp contact-list display branching for multi-facility users (PR #9094); and aggregate targets disabled for those users (PR #9099, a gate PR #9317 lifted on master). The Admin-app place multiselect is separate work (#9116).'
+services:
+  - api
+  - sentinel
+  - webapp
+techStack:
+  - javascript
+  - nodejs
+  - couchdb
+  - express
+  - mocha
+  - typescript
+  - angular
+tags:
+  - user-management
+  - multiple-facilities
+  - authorization
+  - api-versioning
+  - roles
+  - replication-permissions
+related_workflows:
+  - user-registration
+source_pr: medic/cht-core#9126
+source_prs:
+  - "medic/cht-core#9094"
+  - "medic/cht-core#9099"
+  - "medic/cht-core#9126"
+source_sha: 2fdddd07194e104c3958646cc5db9251694c8353
+distilled_at: '2026-06-23'
+reviewed_by: null
+reviewed_at: null
+confidence: medium
+entities:
+  - api/src/controllers/users.js
+  - api/src/routing.js
+  - api/src/services/authorization.js
+  - ddocs/users-db/users/views/users_by_field/map.js
+  - shared-libs/user-management/src/users.js
+  - shared-libs/user-management/src/roles.js
+  - shared-libs/user-management/src/libs/facility.js
+  - shared-libs/contacts/src/places.js
+concepts:
+  - multi-facility user model
+  - API versioning (v3 endpoint)
+  - authorization / replication doc-access scoping
+  - user provisioning
+  - CouchDB design-doc views (users_by_field)
+  - facility-contact association constraints
+  - backwards compatibility
+related_issues:
+  - cht-core-9116
+  - cht-core-9231
+  - cht-core-9433
+stale: true
+---
+
+## Problem
+
+Each CHT user could be linked to only a single facility. Health workers operating across more than one facility could not be represented as one account with access to documents from all their assigned facilities — the v1 users API accepted only one facility, and the authorization logic that computes a user's replicable (download/upload) document set was scoped to a single facility subtree.
+
+## Root Cause
+
+The user-management shared library (shared-libs/user-management/src/users.js, shared-libs/user-management/src/libs/facility.js), the api users controller, the authorization service, and the users_by_field CouchDB view all assumed a single facility_id per user. Doc download/upload permission computation unioned over only one facility's subtree, and the view indexed a single facility, so a user could not be authorized for documents across multiple places.
+
+## Solution
+
+Introduced a new /v3/users API (create and update) that accepts an array of UUIDs of existing facilities, accepting the same payload shape as /v1/users. Only the create side is new code — `POST /api/v3/users` (`users.v3.create` → `createMultiFacilityUser`); `POST /api/v3/users/:username` (`users.v3.update`) calls the v1 update handler, so both update routes accept a `place` array. Updated the user-management shared library to model multiple facilities (`hydratePayload`/`getFacilityId` turn `place` into an array `facility_id`, which user create and update now write) and the authorization service so a user's downloadable/uploadable doc set is the union across all their facilities. More than one place is accepted only when one of the user's roles has the new `can_have_multiple_places` permission (`validateAllowedMultipleFacilities` in shared-libs/user-management/src/users.js — at this PR via a new `hasAllPermissions` in shared-libs/user-management/src/roles.js, which #10795 removed from master in favour of cht-datasource `hasPermissions`), and every listed facility must exist (`placesExist`, added to shared-libs/contacts/src/places.js). Updated the users_by_field view map to index multiple facilities and the `facility_id`/`contact_id` user lookup (`getUsers` in shared-libs/user-management/src/users.js) to match users whose `facility_id` array contains the queried facility. Constraints: when creating a multi-facility user the contact must fall within one of the facilities; v3 does not create facilities or contacts, only links existing facility UUIDs.
+
+On the webapp side (PR #9094), the contacts UI branches on the user's facility count: multi-facility users see only their assigned homeplaces in the left-hand list when not searching (child places are loaded into the selected homeplace's 'places' card in the detail view instead — `shouldGetDescendants` in webapp/src/ts/effects/contacts.effects.ts — and the sort option (`isAllowedToSort`) and homeplace highlight (`isPrimaryContact`) are hidden), while single-facility users keep the existing homeplace-plus-children behavior. Aggregate targets were disabled for multi-facility users: `TargetAggregatesService.isEnabled()` returned false when the user has more than one facility, and `AnalyticsModulesService` switched from checking `can_aggregate_targets` directly to `isEnabled()` when deciding whether the target-aggregates module is available (PR #9099). That gate does not hold on master: PR #9317 (#9231, first released in 4.10.0) changed `isEnabled()` to `!facilityIds || facilityIds.length > 0`, re-enabling aggregate targets for multi-facility users.
+
+## Code Patterns
+
+New API version namespace (`users.v3`) registered in api/src/routing.js, delegating to api/src/controllers/users.js; single-vs-array `place` input is normalized to an array `facility_id` in shared-libs/user-management/src/users.js (`getFacilityId`). api/src/services/authorization.js (present at this PR's anchor; moved on master to api/src/services/replication/authorization.js by #10823) iterates over the user's facility list (`getContactsByDepthKeys`) to union allowed doc subtrees for replication. ddocs/users-db/users/views/users_by_field/map.js emits one index row per facility so multi-facility users are discoverable by any of their places. Facility validation lives in shared-libs/user-management/src/users.js (`validateUserFacility` → `validateAllowedMultipleFacilities`, then `places.placesExist`); shared-libs/user-management/src/libs/facility.js `list()` only gathers the ids — now every entry of an array `facility_id`, plus `contact_id` — for the bulk doc fetch that hydrates user responses.
+
+## Design Choices
+
+Multi-facility creation got its own v3 endpoint instead of changing v1/v2 create, which keep creating the place and contact from the payload; updates got no separate logic — `users.v3.update` delegates to the v1 handler, so `POST /api/v1/users/:username` accepts a `place` array too. v3 deliberately performs no side-effect creation (no facilities, no contact) and only links existing facility UUIDs, keeping the endpoint narrowly scoped. Validation that all facilities share the same contact type was intentionally deferred (called out in the PR as future work); it was later added only in the Admin app (`validateFacilityHierarchy` → `isSameContactType`, PR #9128), and the API still does not check it on master. Requiring the contact to live within one of the facilities preserves contact-facility consistency. From this PR on the API writes `facility_id` as an array whenever a user is created or updated with a place, but existing users can still hold a string, so the webapp normalizes both shapes to an array (`getUserFacilityId` in webapp/src/ts/modules/contacts/contacts.component.ts) and decides display differences (children, sort, highlight, places card) from the facility count (PR #9094).
+
+## Related Files
+
+- api/src/controllers/users.js
+- api/src/routing.js
+- api/src/services/authorization.js (present at this PR's anchor; moved on master to api/src/services/replication/authorization.js by #10823)
+- ddocs/users-db/users/views/users_by_field/map.js
+- shared-libs/user-management/src/users.js
+- shared-libs/user-management/src/roles.js
+- shared-libs/user-management/src/libs/facility.js
+- shared-libs/contacts/src/places.js
+- webapp/src/ts/modules/contacts/contacts.component.ts (PR #9094)
+- webapp/src/ts/modules/contacts/contacts-content.component.ts (PR #9094)
+- webapp/src/ts/modules/contacts/contacts.component.html (PR #9094)
+- webapp/src/ts/effects/contacts.effects.ts (PR #9094)
+- webapp/src/ts/services/target-aggregates.service.ts (PR #9099)
+- webapp/src/ts/services/analytics-modules.service.ts (PR #9099)
+
+## Testing
+
+Updated the existing Mocha unit specs for the users controller, authorization service, user-management roles and users, and contacts places. Integration: replication (`should return all relevant ids with multiple facilities`, plus depth and sensitive-report cases for multiple facilities) and bulk-docs (`should filter offline user requests with multi facility`) cover multi-facility doc download/upload permissions; the users controller spec adds `POST api/v3/users` cases (create with multiple facilities, refusal without the permission, adding facilities on edit, malformed facilities); the sentinel create-user-for-contacts test now expects an array `facility_id`; tests/integration/api/controllers/login.spec.js only gains a random `X-Forwarded-For` header per request. In the wdio e2e suites, db-sync now syncs as a user with two facilities and replace-user expects an array `facility_id`, while edit-person-home-place, person-under-area, offline-user all-permissions (its `all permissions enabled` block only) and target-aggregates were set to `describe.skip` (PR #9099 re-enabled target-aggregates; PR #9128 re-enabled edit-person-home-place and person-under-area; PR #9258 re-enabled all-permissions; PR #9221 later removed tests/e2e/default/contacts/edit-person-home-place.wdio-spec.js from master, moving its one test into tests/e2e/default/contacts/edit.wdio-spec.js as `should sync and update the offline user's home place`). Karma specs for contacts.effects (child places loaded for a multi-facility user, not for a single-facility user's own place) and contacts.component (single vs multi-facility homeplaces) cover the display branching; contacts-content.component.spec only switches its `getUserFacilityId` selector fixture to an array (PR #9094). The target-aggregates.service spec covers `isEnabled()` returning false for more than one facility, analytics-modules.service.spec stubs `isEnabled()`, and the target-aggregates e2e adds `should disable content when user has many facilities associated` (PR #9099).
+
+## Related Issues
+
+- #6543: "Allow for multiple places to be assigned to users" — this draft's issue; PRs #9126, #9094 and #9099 are all stamped `feat(#6543)` on master (so is PR #9093, which restores breadcrumbs for multi-facility users and is not covered here)
+- #9116: "Make place field in the user form a multiselect dropdown" — the Admin-app side of this API, shipped by PR #9128
+- #9231: "Allow users to view aggregate targets and filter by facility_id and reporting period" — PR #9317 under this issue lifted the PR #9099 aggregate-targets gate
+- #9433: "REST Endpoint `/api/v1/users/{{username}}` throwing Server error when updating `contact`" — a 4.9.0 regression in this PR's `validateUserContact`, which mapped over `data.facility_id` (undefined when no `place` is sent); fixed by PR #9437
+
+## Domain Rationale
+
+**Fit:** strong
+
+The work adds user-account provisioning (a new v3 users API to create/update users), role handling, and authorization changes that govern which documents a multi-facility user may download/upload — user management, roles, and access control are canonically the authentication domain, even though the permissions ultimately gate replication. The webapp display facet (PR #9094) and the aggregate-targets gate (PR #9099) are recorded here with the rest of #6543 rather than split into contacts or tasks-and-targets.
diff --git a/agent-memory/domains/authentication/issues/9128-feat9116-update-user-place-field-in-admin-to-allow-setting-m.md b/agent-memory/domains/authentication/issues/9128-feat9116-update-user-place-field-in-admin-to-allow-setting-m.md
new file mode 100644
index 00000000..dcafcba9
--- /dev/null
+++ b/agent-memory/domains/authentication/issues/9128-feat9116-update-user-place-field-in-admin-to-allow-setting-m.md
@@ -0,0 +1,106 @@
+---
+id: cht-core-9116
+category: feature
+domain: authentication
+domainFit: strong
+issueNumber: 9116
+issueUrl: https://github.com/medic/cht-core/issues/9116
+title: Allow assigning multiple places to a user in the Admin app via a multiselect place field, with more than one place requiring can_have_multiple_places
+lastUpdated: '2026-10-05'
+summary: 'The Admin app could only associate a user with a single facility despite backend support for multi-facility users (#6543). This PR makes the user place field a multiselect for every user and creates single users through /api/v3/users; on save, choosing more than one place requires a selected role holding `can_have_multiple_places` and places of the same contact type, and the user''s contact must sit under one of the chosen places.'
+services:
+  - admin
+  - webapp
+  - api
+techStack:
+  - javascript
+  - typescript
+  - angularjs
+  - angular
+  - select2
+tags:
+  - user-management
+  - multiple-places
+  - can_have_multiple_places
+  - roles
+  - permissions
+  - multiselect
+  - facility-association
+  - admin-app
+related_workflows:
+  - user-registration
+source_pr: medic/cht-core#9128
+source_sha: c7fbcb1b88129d9df4ca1cedf1d2a599803acd10
+distilled_at: '2026-06-23'
+reviewed_by: null
+reviewed_at: null
+confidence: medium
+entities:
+  - admin/src/js/controllers/edit-user.js
+  - admin/src/js/services/create-user.js
+  - admin/src/js/services/select2-search.js
+  - admin/src/js/services/contact-types.js
+  - admin/src/templates/edit_user.html
+  - shared-libs/contact-types-utils/src/index.js
+  - webapp/src/ts/modules/contacts/contacts.component.ts
+  - webapp/src/ts/modules/contacts/contacts-more-menu.component.ts
+concepts:
+  - user-place association
+  - role-based permissions
+  - contact hierarchy validation
+  - multiselect form input
+  - user management in admin app
+related_issues:
+  - cht-core-6543
+  - cht-core-9203
+stale: true
+---
+
+## Problem
+
+The CHT Admin app modeled a user's facility as a single-value field, so even after backend support landed for users belonging to multiple facilities (#6543), admins had no way to associate more than one place with a user. This blocked configuring supervisors/CHAs who oversee multiple areas.
+
+## Root Cause
+
+The edit-user controller and admin/src/templates/edit_user.html template bound the user's place to a single-value select2 field (admin/src/js/services/select2-search.js resolved only the first initial value), CreateUser posted single-user creations to `/api/v2/users` rather than the multi-facility `/api/v3/users` endpoint, and the contact-in-place check compared the contact's ancestors against one place id. The admin UI had no concept of the `can_have_multiple_places` permission, which the API had enforced since PR #9126.
+
+## Solution
+
+Made the place field a multiselect select2 dropdown (`multiple="multiple"` on the `id="facilitySelect"` select in admin/src/templates/edit_user.html) for every user, as the issue proposed; the `can_have_multiple_places` permission is checked when the form is submitted, not used to enable the field. On submit, when more than one place is selected, it validates that (a) at least one selected role has `can_have_multiple_places` (`validatePlacesPermission`, via cht-datasource `hasPermissions`) and (b) all selected places have the same contact type (`validateFacilityHierarchy` → `ContactTypes.isSameContactType`; the error text calls this the same hierarchy level); for any selection, (c) the user's contact must have one of the selected places as an ancestor (`validateContactIsInPlace`). Failures show translated errors (`permission.description.can_have_multiple_places.not_allowed` / `permission.description.can_have_multiple_places.incompatible_place`, or `configuration.user.place.contact`). The edit form prefills the multiselect with the user's existing place(s) (`usersPlaces`, passed to Select2Search as `initialValue`); CreateUser's single-user path now posts to `/api/v3/users` (CSV bulk creation stays on `/api/v2/users`), and updates still go to `/api/v1/users/{username}`, which accepts a place array since #9126. Added `isSameContactType` to shared-libs/contact-types-utils (exposed through the admin ContactTypes service), the two error strings to messages-*.properties (en/es/fr/ne/sw), and in the webapp disabled the contact Delete option for a place in the logged-in non-admin user's `facility_id` (`isUserFacility` in webapp/src/ts/modules/contacts/contacts-more-menu.component.ts).
+
+## Code Patterns
+
+Permission-gated validation rather than a gated control — `validatePlacesPermission` in admin/src/js/controllers/edit-user.js checks the selected roles for `can_have_multiple_places` only when more than one place is chosen, mirroring the API's own check (`validateAllowedMultipleFacilities`, #9126). Parameterized select2-search service (admin/src/js/services/select2-search.js) to support multi-selection, reusing existing search infrastructure. The same-type check is a pure helper, `isSameContactType` in shared-libs/contact-types-utils/src/index.js, called only from the Admin app (the API does not call it, at this PR or on master); the parentage check stays in admin/src/js/controllers/edit-user.js (`validateContactIsInPlace`).
+
+## Design Choices
+
+Left the multiselect on for everyone and enforced `can_have_multiple_places` at save time, so single-place users and roles without the permission behave as before — selecting one place never triggers the permission or same-type checks. Put the same-type check in contact-types-utils as a reusable helper; only the Admin app applies it, so the API still accepts places of different types. Reused the existing select2-search component instead of introducing a new widget.
+
+## Related Files
+
+- admin/src/js/controllers/edit-user.js
+- admin/src/js/services/create-user.js
+- admin/src/js/services/select2-search.js
+- admin/src/js/services/contact-types.js
+- admin/src/templates/edit_user.html
+- shared-libs/contact-types-utils/src/index.js
+- api/resources/translations/messages-en.properties
+- webapp/src/ts/modules/contacts/contacts-more-menu.component.ts
+- webapp/src/ts/modules/contacts/contacts-more-menu.component.html
+- webapp/src/ts/modules/contacts/contacts.component.ts
+
+## Testing
+
+Updated admin unit tests: admin/tests/unit/controllers/edit-user.spec.js adds `should allow only user with permission to have multiple places` and `user is updated with multiple places`, and admin/tests/unit/services/update-user.spec.js now expects CreateUser to post to `/api/v3/users`; the shared-libs contact-types-utils tests cover `isSameContactType`. In tests/integration/api/controllers/users.spec.js the `POST/GET api/v2/users` suite was re-enabled (it had been `describe.skip`); no cases were added. E2E: the new tests/e2e/default/contacts/delete-assigned-place.wdio-spec.js logs in as a user with two places and checks that the Delete menu option is disabled on one of them; tests/e2e/default/users/add-user.wdio-spec.js (present at this PR's anchor; renamed on master to tests/e2e/default/users/user.wdio-spec.js by PR #10153, where both cases still exist) adds `should add user with multiple places with permission` and `should require user to have permission for multiple places` (checks the not-allowed message); tests/e2e/default/contacts/edit-person-home-place.wdio-spec.js (present at this PR's anchor; removed on master by PR #9221, which moved its only test into tests/e2e/default/contacts/edit.wdio-spec.js as `should sync and update the offline user's home place`) and tests/e2e/default/contacts/person-under-area.wdio-spec.js (still on master) were re-enabled from `describe.skip`; the users page object gained multiselect place input.
+
+## Related Issues
+
+- #9116: "Make place field in the user form a multiselect dropdown" — this draft's issue, closed by this PR
+- #6543: "Allow for multiple places to be assigned to users" — the API support (PR #9126) this Admin-app work builds on
+- #9203: "Ensure backward compatibility of facility_id in Admin app" — follow-up bug: editing a user whose `facility_id` is still a legacy string failed to load the place, fixed by PR #9204
+
+## Domain Rationale
+
+**Fit:** strong
+
+The PR is user-account management: the Admin-app user form now writes a user's place list (the `facility_id` that scopes what the user may replicate) and refuses more than one place unless a selected role holds the `can_have_multiple_places` permission; the webapp change also stops a user deleting a place assigned to them. Those are user, role and permission concerns rather than contacts or configuration, even though places are contacts and the work happens in the admin tool.
diff --git a/agent-memory/domains/authentication/issues/9131-fix9122-detect-unsafe-redirection-on-login.md b/agent-memory/domains/authentication/issues/9131-fix9122-detect-unsafe-redirection-on-login.md
new file mode 100644
index 00000000..28dbbe00
--- /dev/null
+++ b/agent-memory/domains/authentication/issues/9131-fix9122-detect-unsafe-redirection-on-login.md
@@ -0,0 +1,83 @@
+---
+id: cht-core-9122
+category: bug
+domain: authentication
+domainFit: strong
+issueNumber: 9122
+issueUrl: https://github.com/medic/cht-core/issues/9122
+title: Detect and reject unsafe (double-slash / protocol-relative) redirect URLs on login
+lastUpdated: '2026-09-29'
+summary: The login controller reduced a requested post-login redirect to its path and hash, but a URL whose path itself began with a double slash (typically the CHT host's own URL) came back as a protocol-relative //other-host/... URL, which the browser follows to another site after login. The fix rejects any requested redirect whose path or hash contains a double slash, after repeated percent-decoding, and falls back to the user's home URL.
+services:
+  - api
+techStack:
+  - javascript
+  - node.js
+  - express
+tags:
+  - open-redirect
+  - security
+  - login
+  - redirect-validation
+  - url-sanitization
+  - double-slash
+related_workflows: []
+source_pr: medic/cht-core#9131
+source_sha: b565e13433fdcde4f2e61d47ff96641d7904a5f5
+distilled_at: '2026-06-23'
+reviewed_by: null
+reviewed_at: null
+confidence: medium
+entities:
+  - api/src/controllers/login.js
+concepts:
+  - open redirect prevention
+  - post-login redirect validation
+  - same-origin URL validation
+  - protocol-relative URL handling
+related_issues: []
+stale: true
+---
+
+## Problem
+
+After a successful login, the API login controller answers the login POST with a redirect URL derived from the client-supplied `redirect` value, and the login page script navigates to it (`window.location = xmlhttp.response`). A URL whose path begins with a double slash, such as the same-host `https://demo-cht.dev.medicmobile.org//MYFAKESITE.com/phishing-example/login/`, came back as the protocol-relative `//MYFAKESITE.com/phishing-example/login/`, which browsers treat as another host. A crafted login link could therefore send a freshly authenticated user to an attacker-controlled site (open redirect / phishing vector). The issue's details are in a private tracker.
+
+## Root Cause
+
+At this PR's parent, `getRedirectUrl` (params `userCtx`, `requested`) in api/src/controllers/login.js ran `url.resolve('/', requested)`, parsed the result against a dummy `resolve://` base, and returned `parsed.pathname + (parsed.hash || '')`. That drops any scheme and host, and a requested value that itself starts with `//host` resolves to just its path. A double slash inside the path was kept, though, so the returned string could start with `//`.
+
+## Solution
+
+`getRedirectUrl()` now delegates to `sanitizeRequestedRedirect()`. That function resolves the value with `resolveUrl()`, which at this PR is a try/catch around `url.resolve('/', requested)` (on master, since the ESLint 9 bump in PR #10066, it builds `new URL(requested, new URL('/', 'resolve://'))` instead). It then takes `parsed.pathname + (parsed.hash || '')` as before and rejects the result when `hasDoubleSlash()` finds `//` anywhere in it. `hasDoubleSlash()` keeps percent-decoding while decoding still changes the string, so encoded and double-encoded slashes are caught too. A rejected or unresolvable value falls back to the user's home URL (`getHomeUrl(userCtx)`), so only same-origin paths without `//` are honored.
+
+## Code Patterns
+
+Server-side redirect sanitizing in api/src/controllers/login.js. Reduce the requested target to its path and hash, dropping scheme and host. Then reject it outright if it contains `//` anywhere after recursive percent-decoding (`hasDoubleSlash()`), and fall back to the home URL rather than trying to repair it. Rejecting any `//`, not just a leading one, also refuses otherwise harmless paths such as `/a//b`.
+
+## Design Choices
+
+Validation is enforced server-side in the login controller, and unsafe targets are rejected in favor of the home URL rather than rewritten (for example by collapsing slashes), keeping the allow-list to genuine same-origin relative paths. Only the server-side `getRedirectUrl()` changed. The client-side `getRedirectUrl()` in api/src/public/login/script.js returns the raw `redirect` query parameter when the `username` query parameter matches the entered username. `checkSession()` also uses it to send an already-logged-in user onward (`window.location = getRedirectUrl() || userCtx.home || '/'`), and this PR left it untouched.
+
+## Related Files
+
+- api/src/controllers/login.js
+- api/tests/mocha/controllers/login.spec.js
+
+## Testing
+
+Added two cases to the existing table-driven tests (`Bad URL "${given}" should redirect to root`) for `getRedirectUrl` in api/tests/mocha/controllers/login.spec.js, both expected to return `/`:
+- `https://demo-cht.dev.medicmobile.org//MYFAKESITE.com/phishing-example/login/`
+- a fully percent-encoded `https://demo-cht.dev.medicmobile.org/%2F%61%6C…` path
+
+The existing `Good URL "${requested}" should redirect unchanged` cases were not modified and cover the paths that must still be honored.
+
+## Related Issues
+
+- #9122: "Protect against redirection attack" — this draft's issue (labelled Type: Security; the details are in a private tracker)
+
+## Domain Rationale
+
+**Fit:** strong
+
+The change hardens the login controller's post-authentication redirect handling against open-redirect attacks; login flow and redirect validation are core authentication concerns.
diff --git a/agent-memory/domains/authentication/issues/9422-feat9354-add-button-allowing-unmasking-of-password-when-chan.md b/agent-memory/domains/authentication/issues/9422-feat9354-add-button-allowing-unmasking-of-password-when-chan.md
new file mode 100644
index 00000000..434f696f
--- /dev/null
+++ b/agent-memory/domains/authentication/issues/9422-feat9354-add-button-allowing-unmasking-of-password-when-chan.md
@@ -0,0 +1,101 @@
+---
+id: cht-core-9354
+category: improvement
+domain: authentication
+domainFit: weak
+issueNumber: 9354
+issueUrl: https://github.com/medic/cht-core/issues/9354
+title: Add reveal/unmask password toggle (eye icon) to the change-password flows in webapp User Settings and admin Edit User
+lastUpdated: '2026-09-29'
+summary: Password-change forms in the webapp User Settings modal and the admin App Management Edit User modal had no way to reveal the typed password, unlike the login page. Added an eye-icon button that toggles the password and confirm-password fields together between masked and plaintext so users can confirm there are no typos.
+services:
+  - webapp
+  - admin
+techStack:
+  - typescript
+  - javascript
+  - angular
+  - angularjs
+  - less
+  - html
+tags:
+  - password
+  - reveal-password
+  - unmask
+  - eye-icon
+  - user-settings
+  - edit-user
+  - ui
+  - accessibility
+related_workflows:
+  - ui-extensions
+  - user-registration
+source_pr: medic/cht-core#9422
+source_sha: 0efce626d8459cdd75fc49a3427b0ab77e3f1dfd
+distilled_at: '2026-06-23'
+reviewed_by: null
+reviewed_at: null
+confidence: medium
+entities:
+  - webapp/src/ts/modals/edit-user/update-password.component.ts
+  - webapp/src/ts/modals/edit-user/update-password.component.html
+  - admin/src/js/controllers/edit-user.js
+  - admin/src/templates/edit_user.html
+concepts:
+  - password visibility toggle
+  - input type switching (password/text)
+  - UI consistency across admin (AngularJS) and webapp (Angular)
+  - credential entry usability/accessibility
+related_issues:
+  - cht-core-8311
+stale: true
+---
+
+## Problem
+
+When changing a password through the app — both in the webapp User Settings password modal and the admin App Management Edit User modal — there was no way to reveal the typed password. Users could not verify they had entered the password without typos, even though the login page already offered this (issue #8311, PR #8319).
+
+## Root Cause
+
+The password input fields in the webapp update-password modal and the admin edit-user template were hard-coded to type="password" with no visibility toggle; the reveal-password affordance introduced on the login page for #8311 (PR #8319) had not been extended to the password-change forms.
+
+## Solution
+
+Added an eye-icon button (`id="password-toggle"`) inside the password field's `.password-input-group` that toggles both the password and confirm-password inputs between type "password" and "text". The webapp component (webapp/src/ts/modals/edit-user/update-password.component.ts) keeps `editUserModel.passwordFieldType` (initially `'password'`), which webapp/src/ts/modals/edit-user/update-password.component.html binds to both inputs' `type`, and `togglePasswordMasking()` flips it; the admin AngularJS controller (admin/src/js/controllers/edit-user.js) does the same with `$scope.editUserModel.passwordFieldType` and `$scope.togglePasswordMasking()`, used by admin/src/templates/edit_user.html. Both reuse the login page's icons, `/login/images/show-password.svg` and `/login/images/hide-password.svg` (`SHOW_PASSWORD_ICON` / `HIDE_PASSWORD_ICON`). Styling is in a new password.less in each app — admin/src/css/password.less imported from admin/src/css/main.less, webapp/src/css/password.less imported from webapp/src/css/theme.less. The admin password inputs also lost their `autocomplete="new-password"` attribute in this change (still absent on master).
+
+## Code Patterns
+
+Password reveal toggle: keep the input type itself as model state (`passwordFieldType`, `'password'` or `'text'`), bind it to every password input of the form (`type="{{editUserModel.passwordFieldType}}"`) and flip it on eye-icon click, choosing the icon from the same value. Webapp — `togglePasswordMasking()` in webapp/src/ts/modals/edit-user/update-password.component.ts, bound in webapp/src/ts/modals/edit-user/update-password.component.html; admin — `$scope.togglePasswordMasking()` in admin/src/js/controllers/edit-user.js and admin/src/templates/edit_user.html; each app has its own copy of the styling in password.less.
+
+## Design Choices
+
+Reused the existing reveal-password UX from the login page (#8311, PR #8319), including its icon files, for consistency rather than inventing a new pattern, and applied it across both the admin (AngularJS) and webapp (Angular) surfaces so the behavior is uniform. Styling was factored into a dedicated password.less in each app. One toggle drives both the password and confirm fields, so the user sees both values in the same state.
+
+## Related Files
+
+- admin/src/css/main.less
+- admin/src/css/password.less
+- admin/src/js/controllers/edit-user.js
+- admin/src/templates/edit_user.html
+- admin/tests/unit/controllers/edit-user.spec.js
+- tests/e2e/default/users/add-user.wdio-spec.js (present at this PR's anchor; renamed on master to tests/e2e/default/users/user.wdio-spec.js by PR #10153)
+- tests/page-objects/default/users/user.wdio.page.js
+- webapp/src/css/password.less
+- webapp/src/css/theme.less
+- webapp/src/ts/modals/edit-user/update-password.component.html
+- webapp/src/ts/modals/edit-user/update-password.component.ts
+
+## Testing
+
+The admin unit spec (admin/tests/unit/controllers/edit-user.spec.js) only adds the new `passwordFieldType`, `showPasswordIcon` and `hidePasswordIcon` fields to an expected model; there is no unit test of `togglePasswordMasking()`. The toggle is covered end to end in the admin Edit User modal by a new WebdriverIO case, `should hide and reveal password value, and add user with a revealed password`, in tests/e2e/default/users/add-user.wdio-spec.js (renamed on master to tests/e2e/default/users/user.wdio-spec.js by PR #10153, where the case still exists), using `togglePassword()`, `setUserPassword()` and `setUserConfirmPassword()` added to tests/page-objects/default/users/user.wdio.page.js. The webapp update-password modal has no new test.
+
+## Related Issues
+
+- #9354: "Add password reveal to change password form" — the issue this PR closes
+- #8311: "Show password when clicking on the eye icon" — the login-page reveal feature (implemented by PR #8319) whose pattern and icons this PR reuses
+
+## Domain Rationale
+
+**Fit:** weak
+
+The change is UI-only: an eye-icon toggle that switches the `type` of the password and confirm inputs in the webapp update-password modal and the admin Edit User modal, mirroring the login-page reveal feature added for #8311. It does not change how the password is validated, stored or transmitted, and touches no session or access handling. Authentication is the least-bad home because the only surfaces touched are password-entry forms for user credentials; no app_settings or translation files change, so it is not configuration either.
diff --git a/agent-memory/domains/authentication/issues/9437-fix9433-use-existent-facility-when-updating-user.md b/agent-memory/domains/authentication/issues/9437-fix9433-use-existent-facility-when-updating-user.md
new file mode 100644
index 00000000..92ecd596
--- /dev/null
+++ b/agent-memory/domains/authentication/issues/9437-fix9433-use-existent-facility-when-updating-user.md
@@ -0,0 +1,82 @@
+---
+id: cht-core-9433
+category: bug
+domain: authentication
+domainFit: strong
+issueNumber: 9433
+issueUrl: https://github.com/medic/cht-core/issues/9433
+title: Validate a new contact against the user's stored facility when a user update changes only the contact
+lastUpdated: '2026-09-29'
+summary: 'Since the 4.9.0 multi-facility change (PR #9126), updating only a user''s contact through /api/v1/users/{username} returned a 500, because `validateUserContact` mapped over `data.facility_id`, which is undefined when the payload has no `place`. The fix validates the new contact against the payload''s facility or, failing that, the facility stored on the user doc.'
+services:
+  - api
+techStack:
+  - javascript
+  - nodejs
+  - couchdb
+tags:
+  - user-management
+  - user-update
+  - facility
+  - validation
+  - bug-fix
+related_workflows:
+  - user-registration
+source_pr: medic/cht-core#9437
+source_sha: 7844242f64bd619e2b09b4c7c69a500c6486c896
+distilled_at: '2026-06-23'
+reviewed_by: null
+reviewed_at: null
+confidence: medium
+entities:
+  - shared-libs/user-management/src/users.js
+concepts:
+  - user account management
+  - facility/place association
+  - partial-update field resolution
+  - user update validation
+related_issues:
+  - cht-core-6543
+stale: false
+---
+
+## Problem
+
+Updating a user's contact without re-sending its place — a request to `/api/v1/users/{username}` with body `{"contact": "<contact_id>"}` — returned 500 Server Error. The issue reports it as a regression: the same request worked in 4.8.0 and failed in 4.9.0 and 4.10.0.
+
+## Root Cause
+
+Since PR #9126, `validateUserContact` in shared-libs/user-management/src/users.js checked the new contact with `data.facility_id.map(...)`. `hydratePayload` only sets `data.facility_id` from `data.place`, so when the payload had no `place` it was undefined and the `.map` threw, which surfaced as the 500. The check never looked at the facility already stored on the user doc.
+
+## Solution
+
+Added `validateNewContact`, which checks the contact against `forceArray(data.facility_id || user?.facility_id)` — the payload's facilities if a place was sent, otherwise the user doc's stored `facility_id` — and passes if the contact sits under any of them (`Promise.any` over `validateContact`). The new `forceArray` helper also covers a legacy string `facility_id` and replaces the inline `Array.isArray` checks in `getUsers`, `mapUser` and `getUserSettings`; the offline-role "contact required" branch moved into `validateContactForRoles`, which now reads `data.roles || user?.roles`.
+
+## Code Patterns
+
+Partial-update validation in shared-libs/user-management/src/users.js: when a request changes one field (the contact) whose validity depends on another (the facility), read the dependent value from the payload first and fall back to the merged user doc (`data.facility_id || user?.facility_id`) instead of assuming the caller resent it; normalize string-or-array fields once with `forceArray`.
+
+## Design Choices
+
+Validate against the already-associated facility rather than requiring every contact update to resend the place — before PR #9126 the check used the user doc's `facility_id`, so this restores contact-only updates; `forceArray` keeps users whose stored `facility_id` is still a string working.
+
+## Related Files
+
+- shared-libs/user-management/src/users.js
+- shared-libs/user-management/test/unit/users.spec.js
+- tests/integration/api/controllers/users.spec.js
+
+## Testing
+
+Both test files were modified, not added. The existing shared-libs/user-management/test/unit/users.spec.js gained a case (`should update contact on user and user settings`: a contact-only update keeps `facility_id: ['maine']` and writes the updated `contact_id` to both docs). The existing tests/integration/api/controllers/users.spec.js gained one (`should allow to only update the contact`: POST `/api/v1/users/{username}` with only `contact`, after which both the user-settings and `_users` docs carry the new `contact_id`).
+
+## Related Issues
+
+- #9433: "REST Endpoint `/api/v1/users/{{username}}` throwing Server error when updating `contact`" — this draft's issue
+- #6543: "Allow for multiple places to be assigned to users" — its API PR #9126 introduced the `data.facility_id.map(...)` contact check this fixes
+
+## Domain Rationale
+
+**Fit:** strong
+
+User account creation/update logic in shared-libs/user-management is canonically the authentication domain (user provisioning, roles, and their facility/contact associations); this PR fixes how a changed contact is validated against the user's facility during an update, not contact lookup or place configuration.
diff --git a/agent-memory/domains/authentication/issues/9671-fix9527-dont-log-error-when-privacy-policy-doc-is-malformed.md b/agent-memory/domains/authentication/issues/9671-fix9527-dont-log-error-when-privacy-policy-doc-is-malformed.md
new file mode 100644
index 00000000..16bf3668
--- /dev/null
+++ b/agent-memory/domains/authentication/issues/9671-fix9527-dont-log-error-when-privacy-policy-doc-is-malformed.md
@@ -0,0 +1,87 @@
+---
+id: cht-core-9527
+category: bug
+domain: authentication
+domainFit: weak
+issueNumber: 9527
+issueUrl: https://github.com/medic/cht-core/issues/9527
+title: Treat a privacy-policies doc with no policies as a 404 instead of logging an error
+lastUpdated: '2026-09-29'
+summary: When the `privacy-policies` doc existed but had a missing or empty `privacy_policies` property, the API's privacy-policy service threw a plain `Error` that its own catch passed to `logger.error`, so every login-page render (including service-worker generation) logged a misleading error. The fix throws a new `NotFoundError` (status 404) instead, which that catch does not log, so the doc is treated exactly like a missing one.
+services:
+  - api
+techStack:
+  - javascript
+  - nodejs
+  - couchdb
+  - mocha
+tags:
+  - privacy-policy
+  - error-handling
+  - '404'
+  - malformed-document
+  - logging
+related_workflows:
+  - observability
+source_pr: medic/cht-core#9671
+source_sha: fd83165ace19b618300179569d12858207a72225
+distilled_at: '2026-06-22'
+reviewed_by: null
+reviewed_at: null
+confidence: medium
+entities:
+  - api/src/services/privacy-policy.js
+  - api/src/errors.js
+  - api/src/public-error.js
+  - api/src/services/records.js
+concepts:
+  - error handling
+  - HTTP status codes
+  - graceful degradation
+  - shared error abstractions
+  - privacy policy existence check on the login page
+related_issues: []
+stale: false
+---
+
+## Problem
+
+When the `privacy-policies` doc in the medic database existed but lacked a non-empty `privacy_policies` property (for example after an empty privacy-policies.json configuration was uploaded), the API logged `Invalid privacy-policies doc: missing required "privacy_policies" property` as an error. The error is harmless — the login page simply shows no privacy-policy link — but issue #9527 reports it caused confusion and was often mistaken for an API crash. It was logged on every login-page render, including the one done during service-worker generation, and `GET /medic/privacy-policy` answered 500.
+
+## Root Cause
+
+`getDoc()` in api/src/services/privacy-policy.js threw a plain `Error` when the doc had no policies, and its `.catch` logs every error whose `status` is not 404 before rethrowing — so a doc that is present but unusable was logged like a genuine server error, while a missing doc (a PouchDB 404) was silent. api had no error class carrying a 404 status.
+
+## Solution
+
+Added api/src/errors.js with a `NotFoundError` class that sets both `status` and `statusCode` to 404 (commented as simulating PouchDB and request errors), and made `getDoc()` throw `NotFoundError` for a doc without policies, so the catch no longer logs it. `exists()` still returns false, so the login page shows no policy link, and `GET /medic/privacy-policy` now responds 404 through `serverUtils.error` instead of 500. `PublicError` moved from api/src/public-error.js (deleted) into api/src/errors.js, and api/src/services/records.js — the only module that imported it — now requires `{ PublicError }` from `../errors`. The issue suggested logging a warning with configuration guidance; the PR instead stops logging this case at all.
+
+## Code Patterns
+
+Give an expected absence its own error type that looks like the platform's not-found errors: `NotFoundError` (api/src/errors.js) sets `status` (PouchDB style) and `statusCode` (request style) to 404, so existing checks such as the `err.status !== 404` log filter in api/src/services/privacy-policy.js and `serverUtils.error()` (which reads `err.code || err.statusCode || err.status`) treat a present-but-unusable doc exactly like a missing one, with no special-casing at the call sites. Differentiate expected 'data not usable' conditions from true server errors to avoid log noise. api/src/errors.js became api's shared module for error classes; on master it also holds `PermissionError`, `AuthenticationError`, `ContentTypeError`, `BadRequestError` and `PayloadTooLargeError`.
+
+## Design Choices
+
+Treating a malformed policy doc as 404 (instead of a logged plain `Error` and a 500 from the endpoint) makes failure graceful — clients behave as if no policy exists — and stops the malformed-doc case from polluting error logs. `PublicError` was moved into the same new module rather than left in its own file, so api's error classes live in one place.
+
+## Related Files
+
+- api/src/services/privacy-policy.js
+- api/src/errors.js (added)
+- api/src/public-error.js (deleted)
+- api/src/services/records.js
+- api/tests/mocha/services/privacy-policy.spec.js
+
+## Testing
+
+Added three Mocha unit cases to api/tests/mocha/services/privacy-policy.spec.js — the doc does not exist, `privacy_policies` is empty, and the property is missing — each asserting that `get()` rejects with status 404 and that `logger.error` is not called.
+
+## Related Issues
+
+- #9527: "API logs error when privacy policies doc contains no privacy policies" — the issue this PR closes
+
+## Domain Rationale
+
+**Fit:** weak
+
+The change is error classification and logging in api/src/services/privacy-policy.js: a present-but-empty `privacy-policies` doc now throws a 404 `NotFoundError` instead of a logged plain `Error`. It touches no credential, session or access handling. Authentication is the least-bad home because one of the service's two consumers is the login page render (`privacyPolicy.exists()` in api/src/controllers/login.js decides whether the login page links to the policy); configuration is the other candidate, since the doc is admin-uploaded content, but the PR changes no settings or configuration handling.
diff --git a/agent-memory/domains/authentication/issues/9723-fix9213-fixes-back-button-navigation-after-logout.md b/agent-memory/domains/authentication/issues/9723-fix9213-fixes-back-button-navigation-after-logout.md
new file mode 100644
index 00000000..95a47753
--- /dev/null
+++ b/agent-memory/domains/authentication/issues/9723-fix9213-fixes-back-button-navigation-after-logout.md
@@ -0,0 +1,79 @@
+---
+id: cht-core-9213
+category: bug
+domain: authentication
+domainFit: strong
+issueNumber: 9213
+issueUrl: https://github.com/medic/cht-core/issues/9213
+title: Push a root history entry before redirecting to login so the back button after logout does not return to the admin page
+lastUpdated: '2026-09-29'
+summary: After logging out of the AngularJS admin app, the browser back button loaded the previously authenticated admin page. The fix makes the admin Session service's navigateToLogin() call history.pushState(null, null, '/') just before it navigates to the login page, so the history step immediately behind the login page is / rather than the admin page. It does not remove the earlier entries.
+services:
+  - admin
+techStack:
+  - angularjs
+  - javascript
+tags:
+  - logout
+  - session
+  - back-button
+  - browser-history
+  - navigation
+  - spa
+related_workflows: []
+source_pr: medic/cht-core#9723
+source_sha: 41c424646ac1c9dd5200eaf352a58631b5663637
+distilled_at: '2026-06-22'
+reviewed_by: null
+reviewed_at: null
+confidence: medium
+entities:
+  - admin/src/js/services/session.js
+concepts:
+  - session management
+  - logout flow
+  - browser history manipulation
+  - single-page-application navigation
+  - post-logout access prevention
+related_issues: []
+stale: false
+---
+
+## Problem
+
+After a user logged out of the admin app, pressing the browser back button loaded the authenticated admin page again instead of redirecting to login, exposing content from the ended session (issue #9213, reported on 4.6.0 in Chrome).
+
+## Root Cause
+
+`navigateToLogin()` in admin/src/js/services/session.js removed the `userCtx` cookie and then set `$window.location.href` to `/${Location.dbName}/login?...`. That is an ordinary navigation, so the authenticated admin page stayed as the previous browser-history entry and Back returned to it.
+
+## Solution
+
+`navigateToLogin()` now calls `$window.history.pushState(null, null, '/')` immediately before the `$window.location.href` assignment. The inline comment calls this clearing the browser history, but it adds a same-document entry with URL `/` rather than removing anything. The step immediately behind the login page is therefore `/`, not the admin page URL (the `redirect` query parameter is read from `$window.location.href` before the push, so it still names the admin page). `logout()` (after `$http` `.delete('/_session')`) and `checkCurrentSession()` (on a 401 from `/_session`) both go through `navigateToLogin()`, so every redirect to login gets the extra entry.
+
+## Code Patterns
+
+Push a neutral history entry (`$window.history.pushState(null, null, '/')`) right before a full-page redirect to login, in the one function every logout path shares (`navigateToLogin()` in admin/src/js/services/session.js). It is used in place of SPA navigation-guard events (beforeunload/popstate), which the PR description reports could not block back navigation under AngularJS.
+
+## Design Choices
+
+The PR description reports that event-based interception (beforeunload, popstate, etc.) did not prevent the navigation in Angular v1, and that the history approach worked best in Chrome and Firefox. It calls the result not perfect but a significant improvement. The earlier admin entries remain in history.
+
+## Related Files
+
+- admin/src/js/services/session.js
+- admin/tests/unit/services/session.spec.js
+
+## Testing
+
+Updated admin/tests/unit/services/session.spec.js. The `$window` mock gains a `history.pushState` stub. 'logs out', 'logs out if no user context' and 'logs out if remote userCtx inconsistent' assert it was called once with `(null, null, '/')`. The 401 case ('cookie gets deleted when session expires') gains no `pushState` assertion. 'does not log out if server not found' and 'does not log out if remote userCtx consistent' assert it was not called.
+
+## Related Issues
+
+- #9213: "Admin app allows navigating back after logout" — this draft's issue
+
+## Domain Rationale
+
+**Fit:** strong
+
+The change lives in the admin app's session service and hardens the logout flow, so that the back step after logout no longer lands on the authenticated admin page. Session and logout handling is canonically the authentication domain.
diff --git a/agent-memory/domains/authentication/issues/9731-feat9547-require-password-reset-on-first-time-login-and-admi.md b/agent-memory/domains/authentication/issues/9731-feat9547-require-password-reset-on-first-time-login-and-admi.md
new file mode 100644
index 00000000..c34ba911
--- /dev/null
+++ b/agent-memory/domains/authentication/issues/9731-feat9547-require-password-reset-on-first-time-login-and-admi.md
@@ -0,0 +1,113 @@
+---
+id: cht-core-9547
+category: feature
+domain: authentication
+domainFit: strong
+issueNumber: 9547
+issueUrl: https://github.com/medic/cht-core/issues/9547
+title: Require password reset on first-time login and after admin updates a user's password
+lastUpdated: '2026-10-05'
+summary: Admins create CHW accounts and share a single password, which then stays valid indefinitely with no forced rotation. This PR adds a password-reset flow that requires users to set a new password on first login (and whenever an admin sets or resets their password), enabled by default with a permission to skip it.
+services:
+  - api
+  - admin
+  - webapp
+techStack:
+  - javascript
+  - angularjs
+  - couchdb
+  - service-worker
+  - html
+  - css
+tags:
+  - password-reset
+  - first-login
+  - password-change-required
+  - security
+  - user-management
+  - login-flow
+  - permissions
+  - internationalization
+related_workflows:
+  - user-registration
+source_pr: medic/cht-core#9731
+source_sha: 67b533070d124a274994ce5b3e8a772986a239d1
+distilled_at: '2026-06-22'
+reviewed_by: null
+reviewed_at: null
+confidence: medium
+entities:
+  - api/src/controllers/login.js
+  - api/src/public/login/password-reset.js
+  - api/src/templates/login/password-reset.html
+  - shared-libs/user-management/src/users.js
+  - admin/src/js/controllers/edit-user.js
+  - api/src/services/cookie.js
+concepts:
+  - password-reset enforcement on login
+  - first-time login flow
+  - password_change_required user flag
+  - permission-gated bypass (can_skip_password_change)
+  - cookie/session management
+  - service-worker caching of login assets
+related_issues: []
+stale: true
+---
+
+## Problem
+
+System admins create accounts for CHWs and share the password with them out-of-band. There was no mechanism to force the user to change that shared password on first login, nor to force a change after an admin reset a user's password, so initial/admin-set credentials remained valid indefinitely — a security weakness for newly provisioned accounts.
+
+## Root Cause
+
+Not a bug but a missing capability: the user model and login flow had no notion of a required password change. User documents carried no password_change_required flag, the login controller never redirected to a reset page, and user-management saved admin-set passwords (on create, update or reset) without flagging the account for forced rotation.
+
+## Solution
+
+Introduced a `password_change_required` flag on `_users` docs, set server-side in shared-libs/user-management/src/users.js: whenever an update carries a `password`, `getUserUpdates()` sets it to `data.password_change_required === false ? false : isPasswordChangeRequired(updatedUser, data, fullAccess)`. `isPasswordChangeRequired()` returns false when the caller lacks full access (`can_edit` + `can_update_users`, which is the webapp self-service case for ordinary users) or the update enables token login, and otherwise true unless the user's roles hold `can_skip_password_change`; `createUser()` and `resetPassword()` pass full access, and `updateUser()` passes its `fullAccess` argument.
+
+In api/src/controllers/login.js, `setCookies()` now loads the user doc (`users.getUserDoc`) after authenticating; if the flag is set, `redirectToPasswordReset()` sets only the `userCtx` and locale cookies — not the session cookie — and returns `PASSWORD_RESET_URL` (`/medic/password-reset`). api/src/routing.js serves that page with `login.getPasswordReset` (GET, rendering the new api/src/templates/login/password-reset.html) and handles its form with `login.resetPassword` (POST), which is rate-limited, validates the new password's length and strength, checks the current password with a GET to `/_session` using the submitted credentials, rejects reusing the current password, saves the new one with `password_change_required: false`, and then creates the session and redirects into the app. api/src/services/cookie.js only gained a `clearCookie(res, name)` helper, used to clear the `login` cookie.
+
+In the admin app, `validateSkipPasswordPermission()` in admin/src/js/controllers/edit-user.js computes `$scope.skipPasswordChange` from `can_skip_password_change`, and admin/src/templates/edit_user.html shows the `update.password.help` hint under the Password label when it is false; the admin app does not set `password_change_required` itself. config/default/app_settings.json and config/demo/app_settings.json (both modified) gained a `can_skip_password_change` permission with an empty role list, so by default every role is prompted; a users-API request that sets a password together with `password_change_required: false` skips the prompt for that user.
+
+New login-page strings (`change.password.*`, `password.current.incorrect`, `password.must.match`, `password.same`) were added to the api/resources/translations messages files for ar, en, es, fr, id, ne and sw, and `update.password.help` for en, es, fr, ne and sw only. The webapp bootstrapper (webapp/src/js/bootstrapper/index.js, webapp/src/js/bootstrapper/translator.js) shows a `PASSWORD_CHANGE_SUCCESS` message after the reset page stores `passwordStatus` = `PASSWORD_CHANGED` in localStorage, and api/src/generate-service-worker.js adds `/medic/password-reset` to the service worker's `templatedURLs` next to `/medic/login`.
+
+## Code Patterns
+
+Login client logic is shared between the standard login and the new reset page through a new `window.AuthUtils` module (api/src/public/login/auth-utils.js, added), loaded by the login, token-login and password-reset templates; api/src/public/login/script.js and api/src/public/login/password-reset.js destructure helpers such as `request`, `getUserCtx` and `togglePassword` from it. The `password_change_required` flag on the CouchDB `_users` doc acts as a server-side gate checked in api/src/controllers/login.js (`skipPasswordChange(user)` is `!user?.password_change_required`) to drive the redirect, and the `can_skip_password_change` permission provides the role-based bypass — the standard CHT `can_*` permission pattern, declared in config/default/app_settings.json (and, at this PR, config/demo/app_settings.json, which PR #11354 deleted on master). At this PR `isPasswordChangeRequired()` checks the permission with `roles.hasAllPermissions(userRoles, ['can_skip_password_change'])`; on master it uses `chtDatasource.v1.hasPermissions(['can_skip_password_change'], userRoles)` (changed by PR #10795).
+
+## Design Choices
+
+Enabled by default to satisfy the issue's security-first requirement, with a permission to skip rather than a global on/off toggle so behavior can be scoped per role. The session cookie is withheld until the reset succeeds, so a flagged user cannot reach the app with the shared password. The flag is keyed on the caller's permissions, not on self-versus-other: password changes by a caller without full access (`can_edit` + `can_update_users`, which is the webapp self-service case for ordinary users) and updates that enable token login never set the flag, while a user who holds both permissions (default config: `program_officer`) is flagged even when changing their own password unless their role has `can_skip_password_change`. An API escape hatch (password_change_required: false for a specific user) covers exceptions. The admin app surfaces an explicit hint when changing a password so admins know the user will be prompted, rather than silently flagging the account.
+
+## Related Files
+
+- api/src/controllers/login.js
+- api/src/public/login/password-reset.js
+- api/src/templates/login/password-reset.html
+- api/src/public/login/auth-utils.js
+- api/src/public/login/script.js
+- api/src/routing.js
+- api/src/services/cookie.js
+- api/src/generate-service-worker.js
+- shared-libs/user-management/src/users.js
+- admin/src/js/controllers/edit-user.js
+- admin/src/templates/edit_user.html
+- config/default/app_settings.json
+- config/demo/app_settings.json (present at this PR's anchor; removed on master by the demo-config deletion, PR #11354)
+- webapp/src/js/bootstrapper/index.js
+- api/resources/translations/messages-en.properties
+
+## Testing
+
+No new spec files; existing unit specs were extended for the login controller, cookie service and service-worker generation (api/tests/mocha), the admin edit-user controller (admin/tests/unit), user-management users (shared-libs/user-management/test/unit) and the webapp bootstrapper (webapp/tests/mocha). The integration specs in tests/integration/api/controllers cover the flag being set unless the role has `can_skip_password_change` (tests/integration/api/controllers/users.spec.js) and the login redirect to `/medic/password-reset` for first-time users (tests/integration/api/controllers/login.spec.js). In the WebdriverIO suite, tests/e2e/default/login/login-logout.wdio-spec.js gained a `Password Reset` block (missing fields, weak, mismatched and reused passwords, incorrect current password, and a successful reset), and the service-worker, user/contact creation and replacement specs, the login page object and shared test utils were updated for the new flow.
+
+## Related Issues
+
+- #9547: "Change password on first login" — the issue this PR closes; asks to force a password change for admin-provisioned CHW accounts, on by default with a `can_skip_password_change` bypass
+
+## Domain Rationale
+
+**Fit:** strong
+
+The PR is entirely about the login/password lifecycle — enforcing a password reset on first login and after admin password changes, a new password-reset page and endpoint, withholding the session cookie until the password is changed, and a permission to bypass it — which is squarely authentication: it changes what a successful login yields and how credentials are rotated.
diff --git a/agent-memory/domains/authentication/issues/9800-feat9760-add-support-for-sso-user-createupdate.md b/agent-memory/domains/authentication/issues/9800-feat9760-add-support-for-sso-user-createupdate.md
new file mode 100644
index 00000000..d40ac8eb
--- /dev/null
+++ b/agent-memory/domains/authentication/issues/9800-feat9760-add-support-for-sso-user-createupdate.md
@@ -0,0 +1,105 @@
+---
+id: cht-core-9760
+category: feature
+domain: authentication
+domainFit: strong
+issueNumber: 9760
+issueUrl: https://github.com/medic/cht-core/issues/9760
+title: Add SSO (OIDC) user create/update support to the user-management library and the /api/v1, v2 and v3 users APIs
+lastUpdated: '2026-09-29'
+summary: The user-management library and the users API could not provision CouchDB users that authenticate via SSO/OIDC. This adds an `oidc` boolean field (on master the field is `oidc_username`, which replaced it before the epic landed) to user create/update that sets up SSO users (mutually exclusive with password/token_login), is rejected unless app_settings has `oidc_provider.client_id`, and assigns a random password.
+services:
+  - api
+techStack:
+  - javascript
+  - nodejs
+  - couchdb
+  - oidc
+tags:
+  - sso
+  - oidc
+  - user-management
+  - user-provisioning
+  - openid-connect
+  - authentication
+related_workflows:
+  - user-registration
+source_pr: medic/cht-core#9800
+source_sha: 5f55c171f71daaf872ac000ae32fce8caaa8670a
+distilled_at: '2026-06-22'
+reviewed_by: null
+reviewed_at: null
+confidence: medium
+entities:
+  - shared-libs/user-management/src/sso-login.js
+  - shared-libs/user-management/src/users.js
+concepts:
+  - single-sign-on
+  - oidc-authentication
+  - user-provisioning
+  - identity-federation
+  - mutually-exclusive-auth-methods
+related_issues:
+  - cht-core-9735
+  - cht-core-9890
+stale: true
+---
+
+> **Epic child.** PR #9800 was squash-merged into the feature branch `9735_sso`
+> (`5f55c171f`, 2025-04-12), not into master. That branch reached master as PR #9955
+> (`2cbe9c109`, 2025-06-03). Its own PR number is stamped nowhere on master, which is
+> why this draft's `source_sha` does not resolve in a plain clone. Fetch it with
+> `git fetch origin +refs/pull/9955/head:refs/verify/pr9955` — the epic PR's head ref.
+
+> **Renamed before landing (`stale-as-written`):** this PR's boolean `oidc` user field
+> never reached master. On `9735_sso`, PR #9961 (`4b77459de`) replaced it with a string
+> `oidc_username` (the SSO email, kept unique through the `users/users_by_field` view) plus
+> a boolean `oidc_login` on the user-settings doc, made `validateSsoLogin` async, and changed
+> `isSsoLoginEnabled` from checking `oidc_provider.client_id` to `!!config.get('oidc_provider')`.
+> That later form is what `2cbe9c109` carried to master, and it is what is on master today; the names
+> `validateSsoLogin` and `validateSsoLoginUpdate` in shared-libs/user-management/src/sso-login.js
+> are unchanged.
+
+## Problem
+
+The user-management shared library and the users API create/update endpoints (/api/v1, v2 and v3) had no way to provision CouchDB users that authenticate through SSO/OIDC. Only password and token_login authentication were supported, so SSO users could neither be created nor updated via the API.
+
+## Root Cause
+
+The user create/update logic in shared-libs/user-management/src/users.js handled only password and token_login auth and had no branch for OIDC/SSO users — no field to flag a user as SSO, no check that an OIDC provider is configured in app_settings, and no mechanism to set a placeholder password.
+
+## Solution
+
+Added shared-libs/user-management/src/sso-login.js (`validateSsoLogin`, `validateSsoLoginUpdate`) and wired it into shared-libs/user-management/src/users.js so the user payload accepts an `oidc` boolean (replaced by `oidc_username` before landing). When set, the user is provisioned as an SSO user — rejected if password or token_login is also given, rejected unless app_settings has `oidc_provider.client_id` (internal `isSsoLoginEnabled`, which checks `settings?.oidc_provider?.client_id`), and assigned a generated password (`passwords.generate()`) with `password_change_required: false`. shared-libs/user-management/src/users.js adds `oidc` to `USER_EDITABLE_FIELDS`, stops requiring `password` when `oidc` is set, and calls the validators from `createUser`, `createUsers`, `createMultiFacilityUser` and `updateUser`. The API itself does not check `oidc` at this PR, so password login is not yet blocked; that guard arrived with PR #9887. The issue proposed a string `oidc_provider` user property matched against the app_settings `oidc_provider.client_id`; the PR shipped the boolean `oidc` flag instead, although the JSDoc it added to shared-libs/user-management/src/users.js still documents a `data.oidc_provider` parameter ("Client ID for the OIDC Client").
+
+## Code Patterns
+
+Mutually-exclusive auth-method validation (at this PR, `oidc` cannot be combined with password or token_login) and random-password assignment for federated/SSO users live in shared-libs/user-management/src/sso-login.js; shared-libs/user-management/src/users.js calls them from each create/update path, following the existing token-login validation calls.
+
+## Design Choices
+
+Shipped a boolean `oidc` flag on the `_users` doc (replaced by `oidc_username` before landing) rather than the `oidc_provider` string (client_id match) the issue proposed. The create/update payload carries the same boolean that is stored on the `_users` doc (`'oidc'` in `USER_EDITABLE_FIELDS`). Assigning a generated password gives the account a CouchDB credential that is never returned to the caller (the create response carries only doc ids and revs); explicit rejection of password login for SSO users came later in the epic (PR #9887).
+
+## Related Files
+
+- shared-libs/user-management/src/sso-login.js (added)
+- shared-libs/user-management/src/users.js
+- shared-libs/user-management/test/unit/sso-login.spec.js (added)
+- shared-libs/user-management/test/unit/users.spec.js
+- tests/integration/api/controllers/users.spec.js
+
+## Testing
+
+Added shared-libs/user-management/test/unit/sso-login.spec.js (`validateSsoLogin`, `validateSsoLoginUpdate`) and updated shared-libs/user-management/test/unit/users.spec.js; updated tests/integration/api/controllers/users.spec.js with SSO cases: create via /api/v1, /api/v2 and /api/v3/users, update via /api/v3/users/:username, and rejection when `oidc_provider` is not configured or when password or token_login is combined with `oidc`.
+
+## Related Issues
+
+- #9760: "Update `shared-libs/user-management` to accept an `oidc_provider` property for users" — the issue this PR implements (it shipped a boolean `oidc` flag instead)
+- #9735: "Single sign on (SSO) using identity provider" — the parent epic; this PR reached master inside PR #9955
+- #9890: "Ensure proper mapping for SSO users to Couch users" — replaced this PR's `oidc` flag with `oidc_username` and `oidc_login` (PR #9961)
+
+## Domain Rationale
+
+**Fit:** strong
+
+SSO/OIDC is a login/authentication mechanism; provisioning CouchDB users tied to an OIDC identity provider — mutually exclusive with password/token_login auth — is squarely authentication, not generic user-data management.
diff --git a/agent-memory/domains/authentication/issues/9833-feat9765-add-sso-login.md b/agent-memory/domains/authentication/issues/9833-feat9765-add-sso-login.md
new file mode 100644
index 00000000..ae36c5c7
--- /dev/null
+++ b/agent-memory/domains/authentication/issues/9833-feat9765-add-sso-login.md
@@ -0,0 +1,127 @@
+---
+id: cht-core-9765
+category: feature
+domain: authentication
+domainFit: strong
+issueNumber: 9765
+issueUrl: https://github.com/medic/cht-core/issues/9765
+title: Add SSO login via OpenID Connect (OIDC) with authorization-code callback endpoint
+lastUpdated: '2026-10-05'
+summary: 'CHT only supported CHT-local credentials (username/password and token login) and could not delegate authentication to external identity providers. This PR adds the OIDC authorization-code flow to the API: `oidcAuthorize` (GET /medic/login/oidc/authorize) returns the provider''s authorization URL, and the callback `oidcLogin` (GET /medic/login/oidc) exchanges the authorization_code for an id_token, maps its `preferred_username` claim to a CHT user flagged `oidc` (replaced by the `email` claim and `oidc_username` before the epic reached master), computes a CouchDB AuthSession cookie and redirects into the app — or back to the login page with an `sso_error` message when no eligible CHT user exists.'
+services:
+  - api
+techStack:
+  - javascript
+  - node.js
+  - oidc
+  - openid-connect
+  - openid-client
+  - express
+  - couchdb
+tags:
+  - sso
+  - oidc
+  - openid-connect
+  - single-sign-on
+  - login
+  - authentication
+  - authorization-code-flow
+  - id-token
+related_workflows: []
+source_pr: medic/cht-core#9833
+source_sha: bd9b232437866773a935af2161b68831903c5323
+distilled_at: '2026-06-22'
+reviewed_by: null
+reviewed_at: null
+confidence: medium
+entities:
+  - api/src/services/openid-client.js
+  - api/src/services/sso-login.js
+  - api/src/controllers/login.js
+  - api/src/routing.js
+concepts:
+  - OpenID Connect (OIDC)
+  - single sign-on
+  - authorization code flow
+  - identity federation
+  - id_token validation
+  - session establishment
+  - external identity provider integration
+related_issues:
+  - cht-core-9735
+  - cht-core-9762
+  - cht-core-9890
+  - cht-core-9907
+stale: true
+---
+
+> **Epic child.** PR #9833 was squash-merged into the feature branch `9735_sso`
+> (`bd9b23243`, 2025-05-08), not into master. That branch reached master as PR #9955
+> (`2cbe9c109`, 2025-06-03). Its own PR number is stamped nowhere on master, which is
+> why this draft's `source_sha` does not resolve in a plain clone. Fetch it with
+> `git fetch origin +refs/pull/9955/head:refs/verify/pr9955` — the epic PR's head ref.
+
+> **Superseded before landing (`stale-as-written`):** at this PR, `getIdToken` returns the
+> id_token `preferred_username` claim and `getCookie` looks that name up as the CHT username,
+> requiring the `_users` doc's boolean `oidc` flag (`getUserSalt`); the cookie timestamp is
+> now plus `couch_httpd_auth/timeout`; and `oidcLogin` hands the cookie to `setCookies`.
+> Before `9735_sso` reached master, PR #9887 (`6716fb951`) made `oidcLogin` call
+> `redirectToApp` directly, since `setCookies` rejects SSO users from that PR on; PR #9961
+> (`4b77459de`) switched to the `email` claim matched against `oidc_username` through
+> `getUsersByOidcUsername` (removing `getUserSalt`); commit `15f71f56a` built both URLs from
+> `serverUtils.getAppUrl(req)`; and commit `81c934efa` made the cookie carry the current time.
+> On master, `oidcLogin`, `oidcAuthorize`, both routes and api/src/services/openid-client.js
+> keep their names; api/src/controllers/login.js builds the URLs with its own `getAppUrl()`, which requires
+> `app_url` (PR #10004).
+
+## Problem
+
+CHT authentication was limited to CHT-local credentials (username/password, or token login). Organizations with an existing identity provider had no way to use single sign-on, and there was no mechanism to validate an external OIDC authorization_code or id_token. Additionally, when an SSO user authenticated successfully but no corresponding CHT user existed, there was no defined, user-friendly handling of that failure.
+
+## Root Cause
+
+Missing capability: the login controller and API had no route or service to delegate authentication to an external OIDC provider, exchange an authorization_code for an id_token, or reconcile the federated identity against an existing CHT user account.
+
+## Solution
+
+Added an OIDC SSO flow. A new api/src/services/openid-client.js re-exports `openid-client`'s `discovery`, `buildAuthorizationUrl`, `authorizationCodeGrant` and `allowInsecureRequests` so unit tests can stub the ESM dependency. A new api/src/services/sso-login.js loads the provider by discovery (`oidc_provider.discovery_url`, `client_id` and optional `allow_insecure_requests` from app_settings; client secret from the CHT credential `oidc:client-secret`), builds the authorization URL (`getAuthorizationUrl`, scope `openid email`), exchanges the code (`getIdToken`, calling `authorizationCodeGrant` with `idTokenExpected: true`), and computes the CouchDB `AuthSession` cookie for the matched user (`getCookie` and `makeCookie`: an HMAC-SHA1 keyed by `couch_httpd_auth/secret` plus the user's `salt`). Two handlers in api/src/controllers/login.js, routed in api/src/routing.js, drive it: `oidcAuthorize` (`GET /medic/login/oidc/authorize`) builds the redirect_uri `${req.protocol}://${req.get('host')}/${environment.db}/login/oidc` and returns the provider's authorization URL as the body of a 302 response, which the login page fetches through `requestSSOLogin` (in api/src/public/login/script.js) by XHR and assigns to `window.location`; `oidcLogin` (`GET /medic/login/oidc?code=...`, the redirect target) calls `getIdToken` and `getCookie`, then (at this PR) `setCookies`, and redirects into the app. Any error with `status` 401 from that chain redirects to the login page with the query `sso_error` set to `ssouserinvalid`, which the login page shows as the `login.sso.user_invalid` message; any other error sets it to `loginerror`. At this PR those 401s came from `getUserSalt` (no CHT user with that name, a user not flagged `oidc`, or no `salt`), from token-endpoint 401s that openid-client throws with their `status` (an OAuth error body such as `invalid_client`, or a `WWW-Authenticate` challenge) through `getIdToken` (`authServerCallRetry` rethrows any error with `status` below 500, so these reach `oidcLogin` unchanged; other provider failures, such as a non-200 discovery response, do not arrive with `status` 401 and surface as `loginerror`), and from `setCookies`, whose catch-all threw any failure after the cookie was computed (notably CouchDB rejecting the computed `AuthSession` cookie in `getUserCtxRetry`) as a 401 `Error getting authCtx`, so such failures also surfaced as `ssouserinvalid` rather than `loginerror`. The template api/src/templates/login/index.html moved the `id="login-sso"` button inside the form and added the `sso_user_invalid` error paragraph. api/src/public/login/style.css displays that paragraph in the `ssouserinvalid` state, and the `login.sso.user_invalid` key was added to all nine locale files (ar, bm, en, es, fr, hi, id, ne, sw), with text only in en and sw. `openid-client` (^6.4.2) was added to the root package.json dependencies, and the Node engine requirement moved from >=22.11.0 to >=22.15.0.
+
+## Code Patterns
+
+OIDC authorization-code pattern: the login page's `requestSSOLogin` calls GET /medic/login/oidc/authorize (`oidcAuthorize`) and navigates to the returned provider URL → the provider redirects to GET /medic/login/oidc with a `code` query param → api/src/controllers/login.js `oidcLogin` → api/src/services/sso-login.js `getIdToken` (openid-client `authorizationCodeGrant`, through the api/src/services/openid-client.js wrapper) → `getCookie` resolves the CHT user and builds the `AuthSession` cookie → `oidcLogin` sets the cookies and redirects into the app, or to the login page with `sso_error` on failure. Integration testing pattern: tests/utils/mock-oidc-provider.js stands up a local Express OIDC provider (a discovery document, `/connect/authorize`, and a `/connect/token` endpoint that returns a signed id_token and rejects a missing or `invalid` code) so integration tests can call `login/oidc/authorize` and `login/oidc?code=...` against it.
+
+## Design Choices
+
+When SSO authentication succeeds but no eligible CHT user is found, the flow redirects to the login page with the translatable `login.sso.user_invalid` message rather than failing silently or auto-provisioning a user (the behaviour #9907 asked for). The standard `openid-client` library handles the OIDC protocol, while the CouchDB session cookie is computed locally (`makeCookie`) instead of being obtained from `_session` with a password.
+
+## Related Files
+
+- api/src/services/openid-client.js (added)
+- api/src/services/sso-login.js (added)
+- api/src/controllers/login.js
+- api/src/routing.js
+- api/src/templates/login/index.html
+- api/src/public/login/script.js
+- api/src/public/login/style.css
+- api/tests/mocha/services/sso-login.spec.js (added)
+- api/tests/mocha/controllers/login.spec.js
+- tests/integration/api/controllers/login.spec.js
+- tests/utils/mock-oidc-provider.js (added)
+
+## Testing
+
+Added api/tests/mocha/services/sso-login.spec.js (`getAuthorizationUrl`, `getIdToken`, `getCookie`). The existing api/tests/mocha/controllers/login.spec.js gained `oidcLogin` and `oidcAuthorize` suites, and the existing tests/integration/api/controllers/login.spec.js gained an SSO suite (OIDC not configured, client secret missing, invalid discovery URL, CHT user missing, invalid codes, successful login) backed by the new mock OIDC provider (tests/utils/mock-oidc-provider.js).
+
+## Related Issues
+
+- #9765: "Add support to the CHT api for new endpoint for OIDC login" — the issue this PR implements; it described a single callback handler and an `oidc_provider` check on the `_users` doc, while the PR shipped `oidcLogin` plus `oidcAuthorize` and checks the `oidc` flag
+- #9907: "Handle situation where CHT user does not exist for SSO user" — also closed by this PR: the `sso_error=ssouserinvalid` redirect and `login.sso.user_invalid` message
+- #9735: "Single sign on (SSO) using identity provider" — the parent epic; this PR reached master inside PR #9955
+- #9762: "Update CHT login page to have button for redirecting to OIDC provider" — the 'Login with SSO' button (PR #9877); this PR replaced its client-side `getSSOLoginUrl()` redirect with `requestSSOLogin()`
+- #9890: "Ensure proper mapping for SSO users to Couch users" — replaced this PR's `preferred_username` and `oidc` lookup with the `email` claim and `oidc_username` (PR #9961)
+
+## Domain Rationale
+
+**Fit:** strong
+
+The PR adds Single Sign-On login via OpenID Connect — authorization-code validation, id_token handling, and session establishment for federated identities — which is squarely core authentication functionality.
diff --git a/agent-memory/domains/authentication/issues/9877-feat9762-setup-sso-login-button-and-redirect.md b/agent-memory/domains/authentication/issues/9877-feat9762-setup-sso-login-button-and-redirect.md
new file mode 100644
index 00000000..48d45d63
--- /dev/null
+++ b/agent-memory/domains/authentication/issues/9877-feat9762-setup-sso-login-button-and-redirect.md
@@ -0,0 +1,111 @@
+---
+id: cht-core-9762
+category: feature
+domain: authentication
+domainFit: strong
+issueNumber: 9762
+issueUrl: https://github.com/medic/cht-core/issues/9762
+title: Add a 'Login with SSO' button to the login page, shown only when an OIDC provider is configured
+lastUpdated: '2026-09-29'
+summary: 'When an OIDC provider is configured for a CHT instance there was no way to initiate SSO from the login page. This PR adds a ''Login with SSO'' button, rendered only when app_settings has `oidc_provider`, whose click handler sends the browser to /medic/login/oidc (a route that did not exist yet at this PR; PR #9833 added it and rerouted the button through login/oidc/authorize), plus the `login.sso` translation key in nine locale files.'
+services:
+  - api
+techStack:
+  - javascript
+  - nodejs
+  - oidc
+  - html
+tags:
+  - sso
+  - oidc
+  - openid-connect
+  - login
+  - authentication
+  - redirect
+  - single-sign-on
+related_workflows: []
+source_pr: medic/cht-core#9877
+source_sha: d60a08fdd58a5095fb97a2adf036b33556bc67ca
+distilled_at: '2026-06-22'
+reviewed_by: null
+reviewed_at: null
+confidence: medium
+entities:
+  - api/src/controllers/login.js
+  - api/src/public/login/script.js
+  - api/src/services/settings.js
+  - api/src/templates/login/index.html
+concepts:
+  - OpenID Connect (OIDC)
+  - single sign-on (SSO)
+  - client-side redirect to the SSO login endpoint
+  - login flow
+  - conditional UI rendering based on settings
+related_issues:
+  - cht-core-9735
+  - cht-core-9765
+  - cht-core-9890
+stale: true
+---
+
+> **Epic child.** PR #9877 was squash-merged into the feature branch `9735_sso`
+> (`d60a08fdd`, 2025-04-16), not into master. That branch reached master as PR #9955
+> (`2cbe9c109`, 2025-06-03). Its own PR number is stamped nowhere on master, which is
+> why this draft's `source_sha` does not resolve in a plain clone. Fetch it with
+> `git fetch origin +refs/pull/9955/head:refs/verify/pr9955` — the epic PR's head ref.
+
+> **Superseded before landing (`stale-as-written`):** two pieces of this PR did not reach
+> master. `getSSOLoginUrl` in api/src/public/login/script.js was replaced by PR #9833
+> (`bd9b23243`) with `requestSSOLogin`, which requests `/medic/login/oidc/authorize` and
+> navigates to the provider URL it returns. `hasOidcProvider()` in api/src/services/settings.js
+> was removed by PR #9961 (`4b77459de`); since then `renderLogin` passes
+> `hasOidcProvider: ssoLogin.isSsoLoginEnabled()` from `@medic/user-management` (true when
+> `oidc_provider` is set). The template variable `hasOidcProvider`, the `id="login-sso"` button
+> and the `login.sso` key are still on master.
+
+## Problem
+
+When an OIDC provider was configured for a CHT instance, the login page offered no way for users to authenticate via SSO — only username/password login was available, so users could not be redirected to their SSO provider's login page.
+
+## Root Cause
+
+Feature gap rather than a defect: the login template, controller, and client script had no UI element or redirect logic to detect a configured OIDC provider and send the user to the provider's authorization endpoint.
+
+## Solution
+
+Added a 'Login with SSO' button to the login page template that is shown when an OIDC provider is configured: a new `hasOidcProvider()` in api/src/services/settings.js (removed before landing) returns `!!settings?.oidc_provider`, `renderLogin` in api/src/controllers/login.js (now async) passes its result to the template as `hasOidcProvider`, and api/src/templates/login/index.html renders `<button id="login-sso" class="btn" translate="login.sso">` inside `<% if(hasOidcProvider) { %>`, just after the login form. In api/src/public/login/script.js a click listener on `document.getElementById('login-sso')` calls `getSSOLoginUrl()` (replaced before landing by `requestSSOLogin`), which sets `window.location.href = '/medic/login/oidc'`. The API has no such route at this PR (PR #9833 added it), and no authorization URL is built here: `openid-client` is not yet a dependency of api or the root package. The `login.sso` key was added to nine locale files (ar, bm, en, es, fr, hi, id, ne, sw), with text in en, es, fr, ne and sw and empty values in ar, bm, hi and id. api/package.json's `run-watch` script now passes `-e js,json,html,properties` to nodemon, so template and translation edits also restart the dev server.
+
+## Code Patterns
+
+Conditionally render the SSO button based on whether an OIDC provider is configured (api/src/templates/login/index.html, with the flag computed at this PR by `hasOidcProvider()` in api/src/services/settings.js and passed in by `renderLogin` in api/src/controllers/login.js); client-side navigation to the SSO endpoint in api/src/public/login/script.js.
+
+## Design Choices
+
+The issue proposed obtaining the redirect URL from `openid-client` and storing the OIDC client_secret as a CHT credential; neither is in this PR, and both arrived with PR #9833. The SSO button is gated on OIDC being configured so existing password login is unaffected (backwards compatible). At this PR, and still at the epic squash `2cbe9c109`, the `getElementById('login-sso')` listener is attached without a null check, so on a login page rendered without the button the `DOMContentLoaded` handler throws before `checkUnsupportedBrowser()` runs; master guards it (`if (ssoLoginButton)`) since PR #10414.
+
+## Related Files
+
+- api/package.json
+- api/src/controllers/login.js
+- api/src/public/login/script.js (its `getSSOLoginUrl` was replaced before landing by `requestSSOLogin`, PR #9833)
+- api/src/services/settings.js (its `hasOidcProvider()` was removed before landing by PR #9961)
+- api/src/templates/login/index.html
+- api/tests/mocha/controllers/login.spec.js
+- api/resources/translations/messages-en.properties
+
+## Testing
+
+Updated api/tests/mocha/controllers/login.spec.js (Mocha): at this PR the `get` and `renderLogin` suites stub the settings service's `hasOidcProvider` (`sinon.stub(settings, 'hasOidcProvider').resolves(false)`) and assert it is called on each render. No test exercises the SSO button (`id="login-sso"`) or its click handler.
+
+## Related Issues
+
+- #9762: "Update CHT login page to have button for redirecting to OIDC provider" — the issue this PR implements (the button and a client-side redirect; the redirect to the provider itself came with PR #9833)
+- #9765: "Add support to the CHT api for new endpoint for OIDC login" — delivered the /medic/login/oidc endpoint this button targets, plus the login/oidc/authorize step (PR #9833)
+- #9735: "Single sign on (SSO) using identity provider" — the parent epic; this PR reached master inside PR #9955
+- #9890: "Ensure proper mapping for SSO users to Couch users" — removed this PR's `settings.hasOidcProvider()`; the login render passes `hasOidcProvider: ssoLogin.isSsoLoginEnabled()` instead (PR #9961)
+
+## Domain Rationale
+
+**Fit:** strong
+
+The PR adds the SSO entry point to the login page — a 'Login with SSO' button, gated on OIDC being configured, that starts the SSO login — which is squarely authentication. The translation files are incidental i18n for the new button text, not the PR's primary purpose, so they don't pull this toward configuration.
diff --git a/agent-memory/domains/authentication/issues/9887-feat9763-update-default-login-flow-to-not-allow-sso-users.md b/agent-memory/domains/authentication/issues/9887-feat9763-update-default-login-flow-to-not-allow-sso-users.md
new file mode 100644
index 00000000..8c15df2c
--- /dev/null
+++ b/agent-memory/domains/authentication/issues/9887-feat9763-update-default-login-flow-to-not-allow-sso-users.md
@@ -0,0 +1,109 @@
+---
+id: cht-core-9763
+category: feature
+domain: authentication
+domainFit: strong
+issueNumber: 9763
+issueUrl: https://github.com/medic/cht-core/issues/9763
+title: Block SSO/OIDC users from default password login and password reset flows
+lastUpdated: '2026-10-05'
+summary: 'Nothing in the default username/password login or the reset-password flow rejected a user flagged for SSO; the random password user-management assigns SSO users was the only barrier. This PR adds an `isOidcUser` guard to api/src/controllers/login.js so `setCookies` (the step every password-based login finishes through) answers 401 `Password Login Not Permitted For SSO Users` and `resetPassword` answers 400 before the password is changed. As written here the guard reads the user doc''s `oidc` boolean; on master it reads `oidc_username` instead, re-keyed before landing (see the banner).'
+services:
+  - api
+techStack:
+  - javascript
+  - nodejs
+  - express
+  - couchdb
+  - mocha
+tags:
+  - sso
+  - oidc
+  - login
+  - password-reset
+  - authentication
+  - security-hardening
+related_workflows: []
+source_pr: medic/cht-core#9887
+source_sha: 6716fb951251f6318e2ceef1c88b0874cfa4723d
+distilled_at: '2026-06-22'
+reviewed_by: null
+reviewed_at: null
+confidence: medium
+entities:
+  - api/src/controllers/login.js
+concepts:
+  - single sign-on
+  - OIDC authentication
+  - password-based login
+  - credential validation
+  - authentication gating
+related_issues:
+  - cht-core-9735
+stale: true
+---
+
+> **Epic child.** PR #9887 was squash-merged into the feature branch `9735_sso`
+> (`6716fb951`, 2025-05-08), not into master. That branch reached master as PR #9955
+> (`2cbe9c109`, 2025-06-03). Its own PR number is stamped nowhere on master, which is
+> why this draft's `source_sha` does not resolve in a plain clone. Fetch it with
+> `git fetch origin +refs/pull/9955/head:refs/verify/pr9955` — the epic PR's head ref.
+>
+> **Superseded before landing (`stale-as-written`):** as this PR wrote it, `isOidcUser`
+> is `userDoc?.oidc === true && config.get('oidc_provider')?.client_id`. Inside the epic,
+> PR #9961 (`4b77459de`) replaced the per-user `oidc` boolean with the string
+> `oidc_username` and rewrote the predicate as
+> `userDoc?.oidc_username && ssoLogin.isSsoLoginEnabled()`, where `isSsoLoginEnabled`
+> (shared-libs/user-management/src/sso-login.js) is `!!config.get('oidc_provider')` and no
+> longer requires a `client_id`. That form reached master in `2cbe9c109` and is still
+> there; on master a user doc with `oidc: true` and no `oidc_username` is not blocked.
+> The same PR changed `resetPassword`'s catch to `err.error || err.message || ...`, so on
+> master that 400's body is `Password Reset Not Permitted For SSO Users`. The guard sites
+> (`setCookies`, `resetPassword`), error strings and statuses are otherwise unchanged on
+> master.
+
+## Problem
+
+Nothing in the default login path or the reset-password flow looked at whether a user was provisioned for SSO. At this commit an SSO user is a `_users` doc with `oidc: true` (the flag PR #9800 added to user-management), and the only thing between such a user and the username/password form was the random password user-management generates for them. A user whose password was known — the integration test sets `oidc: true` directly on a user created with a password — could sign in, or change the password through the reset-password flow, without going through the identity provider.
+
+## Root Cause
+
+`setCookies` in api/src/controllers/login.js — which `login` (behind the `post` handler), `resetPassword` and `loginByToken` all call once CouchDB has accepted the credentials — went straight from `users.getUserDoc` to the forced-password-change check and `redirectToApp`, and `resetPassword`, after `passwordResetValidation`, went from `users.getUserDoc` straight to `updatePassword`. Neither inspected the user doc for an SSO flag, so SSO users were treated like any password user.
+
+## Solution
+
+Added `const isOidcUser = (userDoc) => userDoc?.oidc === true && config.get('oidc_provider')?.client_id;` (this commit's form; see the banner) to api/src/controllers/login.js, and two guards:
+
+- `setCookies` throws `unauthorizedError('Password Login Not Permitted For SSO Users')` (an `Error` with `status = 401`) right after loading the user doc, before the password-change redirect and before `redirectToApp` forwards the CouchDB session cookie, so the `post` login answers `401 { error: 'Password Login Not Permitted For SSO Users' }`.
+- `resetPassword` throws a 400 `Password Reset Not Permitted For SSO Users` after `passwordResetValidation` and before `updatePassword`, so the stored password is never changed. At this commit that handler's catch returns `err.error || 'Error updating password'`, so the 400's body is the generic `Error updating password`.
+
+Because `oidcLogin` (the SSO callback) previously finished through `setCookies` too, it now calls `getUserCtxRetry` and `redirectToApp` directly, so neither the new guard nor the forced-password-change redirect applies to SSO sign-ins. Supporting refactors: `getSessionCookie` now throws the 401 `Not logged in` itself, `setCookies` lost its try/catch (`getUserCtxRetry` now logs and throws the 401 `Error getting authCtx`), and `sendLoginErrorResponse` passes 400s through as well as 401s, answering with `e.error || e.message`.
+
+## Code Patterns
+
+One predicate, checked at the shared post-authentication step: `isOidcUser(userDoc)` in api/src/controllers/login.js is evaluated inside `setCookies`, which every password-based path (`login`, `resetPassword`'s re-login, `loginByToken`) calls after CouchDB accepts the credentials, so one guard covers all of them, while the SSO callback `oidcLogin` is routed around `setCookies`. Errors are thrown as `Error` objects carrying `status`, and `sendLoginErrorResponse` maps 400/401 to `{ error: e.error || e.message }`.
+
+## Design Choices
+
+The issue, as edited, asks for the check in the `post` function of api/src/controllers/login.js (its `get` is struck through); its title and first bullet name a per-user `oidc_provider`, and its second bullet was edited from `oidc_provider` to `oidc`. What shipped keys on the `oidc` flag that user-management (PR #9800) writes to the user doc at this commit, and puts the check in `setCookies` rather than in `post`, so it also covers the reset-password re-login and `loginByToken`. The PR also blocks the reset-password flow, which the issue did not ask for. `isOidcUser` requires the app_settings `oidc_provider` to carry a `client_id` at this commit, so a user flagged `oidc` is not locked out of password login on an instance where SSO is not configured. The check runs after CouchDB has validated the credentials — a wrong password still gets the ordinary `Not logged in` 401 — and before any cookie reaches the client.
+
+## Related Files
+
+- api/src/controllers/login.js
+- api/tests/mocha/controllers/login.spec.js
+- tests/integration/api/controllers/login.spec.js
+
+## Testing
+
+Both spec files are modified. api/tests/mocha/controllers/login.spec.js gains 'returns 401 when SSO user attempts password login and SSO is enabled' (`getUserDoc` resolves `{ oidc: true }`, `oidc_provider.client_id` configured; asserts 401 `Password Login Not Permitted For SSO Users`), and tests/integration/api/controllers/login.spec.js gains 'should fail if sso user', which creates a user with a password, writes `oidc: true` onto its `_users` doc and expects the same 401. Both cases are still on master, with their fixtures switched from `oidc: true` to `oidc_username` by PR #9961. The reset-password block has no assertion at this commit: the unit case titled 'should return 400 if is SSO User' posts a too-short password and asserts the `password-short` error. Later in the epic PR #9961 rewrote that case to assert `Password Reset Not Permitted For SSO Users`, and that version is on master.
+
+## Related Issues
+
+- #9763: "Update non-SSO login flow to not allow login if `oidc_provider` set for user" — this draft's issue; as edited, it asks for a check in the login controller's `post` (`get` struck through) of the user's `oidc` value (edited from `oidc_provider`, which the title still uses), plus integration tests.
+- #9735: "Single sign on (SSO) using identity provider" — the SSO epic this PR is a child of.
+
+## Domain Rationale
+
+**Fit:** strong
+
+The PR modifies the login controller to gate password-based login and password reset based on a user's SSO/OIDC status — login, credential validation, and SSO provider handling are core authentication concerns.
diff --git a/agent-memory/domains/authentication/issues/9900-feat9761-add-support-for-sso-users-to-admin-app.md b/agent-memory/domains/authentication/issues/9900-feat9761-add-support-for-sso-users-to-admin-app.md
new file mode 100644
index 00000000..05009318
--- /dev/null
+++ b/agent-memory/domains/authentication/issues/9900-feat9761-add-support-for-sso-users-to-admin-app.md
@@ -0,0 +1,114 @@
+---
+id: cht-core-9761
+category: feature
+domain: authentication
+domainFit: strong
+issueNumber: 9761
+issueUrl: https://github.com/medic/cht-core/issues/9761
+title: Add an SSO Email Address (oidc_username) text field to the admin app user modal, hiding password and token_login for SSO users
+lastUpdated: '2026-09-29'
+summary: 'The admin app''s user create/edit modal had no way to mark a user as an SSO user. This PR adds an "SSO Email Address" text input (`<input id="sso-login" type="text">`, bound to `editUserModel.oidc_username`) that renders only when app_settings has an `oidc_provider`; while it holds a value the token_login controls and password fields are hidden and password validation is skipped. For an existing user whose user-settings doc has `oidc_login`, the modal loads `oidc_username` from `GET /api/v2/users/<name>`, which user-management now returns.'
+services:
+  - admin
+  - api
+techStack:
+  - javascript
+  - angularjs
+  - oidc
+  - couchdb
+tags:
+  - sso
+  - oidc
+  - user-management
+  - admin-app
+  - authentication
+  - oidc_username
+  - token-login
+related_workflows:
+  - user-registration
+source_pr: medic/cht-core#9900
+source_sha: fd3bf4a4080037ab7b913dfc43260c74fddc0fc0
+distilled_at: '2026-06-22'
+reviewed_by: null
+reviewed_at: null
+confidence: medium
+entities:
+  - admin/src/js/controllers/edit-user.js
+  - admin/src/templates/edit_user.html
+  - shared-libs/user-management/src/sso-login.js
+  - shared-libs/user-management/src/token-login.js
+  - shared-libs/user-management/src/users.js
+concepts:
+  - single sign-on (SSO)
+  - OIDC identity provider
+  - mutually-exclusive login methods
+  - user authentication configuration
+  - SSO email address (oidc_username) as the per-user SSO key
+related_issues:
+  - cht-core-9735
+  - cht-core-10062
+stale: true
+---
+
+> **Epic child.** PR #9900 was squash-merged into the feature branch `9735_sso`
+> (`fd3bf4a40`, 2025-05-22), not into master. That branch reached master as PR #9955
+> (`2cbe9c109`, 2025-06-03). Its own PR number is stamped nowhere on master, which is
+> why this draft's `source_sha` does not resolve in a plain clone. Fetch it with
+> `git fetch origin +refs/pull/9955/head:refs/verify/pr9955` — the epic PR's head ref.
+
+## Problem
+
+The admin app's user create/edit modal offered only password and token_login. The users API could already provision SSO users — user-management accepts an `oidc_username` (introduced inside the epic by PR #9961, replacing PR #9800's `oidc` boolean) and rejects combining it with a password or token_login — but the modal had no field for it, so it could neither create an SSO user nor switch an existing user to or from SSO.
+
+## Root Cause
+
+This is a feature gap rather than a defect: admin/src/js/controllers/edit-user.js and admin/src/templates/edit_user.html predated SSO support — neither mentions `oidc` or SSO at this PR's parent — so there was no `oidc_username` input, and the password and token_login controls knew nothing of an SSO mode that should hide them.
+
+## Solution
+
+Added an "SSO Email Address" text input to admin/src/templates/edit_user.html — `<input id="sso-login" type="text" class="form-control" ng-model="editUserModel.oidc_username" />`, label key `user.sso.username`. It renders only when `allowSSOLogin` is truthy — `const allowSSOLogin = settings => settings.oidc_provider;` in admin/src/js/controllers/edit-user.js, i.e. an OIDC provider is configured in app_settings — and the user neither has token login nor is having it switched on (it also shows while an existing token login is being switched off). While `oidc_username` has a value and SSO is allowed, both token-login blocks are removed (`ng-if`) and the password/confirm fields get the `hidden` class; `validatePasswordForEditUser` then skips password validation and clears any typed password, and blanking the field (`oidc_username === ''`) makes a password required again. When SSO is not allowed, `validatePasswordFields` blanks a leftover `oidc_username` whenever it runs, and `validateTokenLogin` does so when token login is on and the phone number validates.
+
+For existing users the modal is opened with the user-settings doc from the admin users list, which carries `oidc_login` but not `oidc_username` (that lives on the `_users` doc). The new `getOidcUsername()` therefore issues `GET /api/v2/users/<name>` — only when `$scope.model.oidc_login` is set — and `determineEditUserModel` now waits for it with `$q.all([Settings(), getOidcUsername()])`. Three keys were added to api/resources/translations/messages-en.properties: `user.sso.username`, `user.sso.username.help` and `user.sso.username.duplicate`.
+
+Supporting user-management changes: `mapUser` in shared-libs/user-management/src/users.js now returns `oidc_username` (what that GET reads); `validateSsoLogin` in shared-libs/user-management/src/sso-login.js rejects only `token_login === true` alongside `oidc_username` (so an explicit `token_login: false` can accompany it) and tags the duplicate-`oidc_username` error with the `user.sso.username.duplicate` key, which shared-libs/user-management/src/users.js now passes to `error400`; `validateSsoLoginUpdate` also rejects setting `oidc_username` on a user whose token_login stays enabled, unless the same update sends `token_login: false`; and `validateTokenLoginEdit` in shared-libs/user-management/src/token-login.js accepts `oidc_username` in place of a password when token login is being disabled.
+
+## Code Patterns
+
+Settings-gated, mutually exclusive login-method fields in AngularJS: `$scope.allowSSOLogin = allowSSOLogin(settings)` (admin/src/js/controllers/edit-user.js) gates the SSO block with `ng-if`, and the token-login blocks and password fields key off `allowSSOLogin && editUserModel.oidc_username` (`ng-if` / `hidden` class) in admin/src/templates/edit_user.html, with `validatePasswordForEditUser` applying the same rule on save. Fetch-on-open for a field that lives only on `_users`: `getOidcUsername()` runs only when the list's user-settings doc has `oidc_login`. The server-side rules stay in shared-libs/user-management/src/sso-login.js (`validateSsoLogin`, `validateSsoLoginUpdate`), with the token-login side in shared-libs/user-management/src/token-login.js (`validateTokenLoginEdit`).
+
+## Design Choices
+
+The issue proposed a checkbox toggle that sets a per-user `oidc_provider`; what shipped is a free-text field bound to `oidc_username`, matching the model PR #9961 had introduced in the commit directly before this one on `9735_sso`: a non-empty `oidc_username` is itself what marks a user as SSO, and the help text (`user.sso.username.help`) tells admins the value must match the user's email at the SSO provider. `oidc_provider` appears here only as the app_settings gate: with no provider configured the field never renders, and the password and token-login validators blank a leftover value. In the UI, SSO is mutually exclusive with password and token_login (the other controls are hidden and a typed password is cleared), matching the validation user-management already enforces; the user-management changes in this PR adjust that validation for the admin's edit flows (switching token_login off while setting `oidc_username`, showing a translated duplicate error).
+
+## Related Files
+
+- admin/tests/unit/controllers/edit-user.spec.js
+- api/resources/translations/messages-en.properties
+- shared-libs/user-management/test/unit/sso-login.spec.js
+- shared-libs/user-management/test/unit/token-login.spec.js
+- shared-libs/user-management/test/unit/users.spec.js
+- tests/integration/api/controllers/users.spec.js
+- tests/e2e/default/users/add-user.wdio-spec.js (present at this PR's anchor; renamed on master to tests/e2e/default/users/user.wdio-spec.js by PR #10153)
+- tests/e2e/default/users/create-meta-db.wdio-spec.js
+- tests/page-objects/default/users/user.wdio.page.js
+- tests/e2e/default/contacts/delete-assigned-place.wdio-spec.js
+- tests/e2e/default/contacts/person-under-area.wdio-spec.js
+- tests/e2e/visual/contacts/contact-user-hierarchy-creation.wdio-spec.js
+
+## Testing
+
+All test files are modified, none added. admin/tests/unit/controllers/edit-user.spec.js gains cases for the password rules around `oidc_username` — not required and cleared when SSO is set on a new user, required again when SSO is removed, switching between SSO and token login in either direction, and no-op saves leaving `oidc_username` untouched. The shared-libs/user-management specs cover `mapUser` returning `oidc_username`, `token_login: false` alongside `oidc_username`, `validateTokenLoginEdit` accepting `oidc_username`, and the translation key on SSO errors; tests/integration/api/controllers/users.spec.js covers the GET returning `oidc_username`, rejecting duplicates, and switching an existing token_login user to SSO. In e2e, `inputAddUserFields` in the users page object tests/page-objects/default/users/user.wdio.page.js changed from positional arguments to an options object with an `oidcUsername` option that fills `#sso-login`. The contacts, create-meta-db and visual specs changed only for that call-site update, and tests/e2e/default/users/add-user.wdio-spec.js (tests/e2e/default/users/user.wdio-spec.js on master, after PR #10153) gained 'should add sso user', which creates a user through the modal and asserts `oidc_username` on the `_users` doc and `oidc_login: true` on the user-settings doc.
+
+## Related Issues
+
+- #9761: "Update user creation frontend to support creating SSO users" — this draft's issue; it proposed a checkbox toggle that sets `oidc_provider` and disables password/token_login configuration; the PR shipped the `oidc_username` text field instead.
+- #9735: "Single sign on (SSO) using identity provider" — the SSO epic this PR is a child of.
+- #10062: "Rendering issue in edit user modal for SSO user" — the extra `getOidcUsername()` request added here delays `determineEditUserModel()` for SSO users, which exposed a latent race in the modal's Select2 setup; fixed on master by PR #10153.
+- PR #9800: "feat(#9760): add support for sso user create/update" — added shared-libs/user-management/src/sso-login.js (`validateSsoLogin`, `validateSsoLoginUpdate`), which this PR adjusts; its `oidc` boolean had already been replaced by `oidc_username` when this PR merged.
+- PR #9961: "feat(#9890): add mapping from OIDC to CHT user" — introduced the `oidc_username` / `oidc_login` fields this UI reads and writes.
+
+## Domain Rationale
+
+**Fit:** strong
+
+The PR adds the admin-app controls for configuring a user to authenticate via SSO — an `oidc_username` field that is mutually exclusive with password and token_login, gated on the app_settings `oidc_provider` — plus the user-management validation adjustments behind them. Per-user login-method configuration is an authentication concern, so this belongs to authentication rather than configuration or contacts.
diff --git a/agent-memory/domains/authentication/issues/9901-feat9764-update-tokenlogin-flow-to-not-allow-oidc-user.md b/agent-memory/domains/authentication/issues/9901-feat9764-update-tokenlogin-flow-to-not-allow-oidc-user.md
new file mode 100644
index 00000000..d29590f1
--- /dev/null
+++ b/agent-memory/domains/authentication/issues/9901-feat9764-update-tokenlogin-flow-to-not-allow-oidc-user.md
@@ -0,0 +1,105 @@
+---
+id: cht-core-9764
+category: feature
+domain: authentication
+domainFit: strong
+issueNumber: 9764
+issueUrl: https://github.com/medic/cht-core/issues/9764
+title: Block OIDC-configured users from authenticating via the token_login flow
+lastUpdated: '2026-09-29'
+summary: 'A user flagged for SSO could still complete the token_login flow and receive a session, bypassing the identity provider. This PR adds a guard to `getUserByToken` in shared-libs/user-management/src/token-login.js — as written here `user.oidc && config.get().oidc_provider?.client_id`, where `oidc` is the per-user truthy flag and `oidc_provider` the app_settings provider config — that rejects with 401 `Token login not allowed for SSO users` before `loginByToken` in api/src/controllers/login.js resets the password or creates a session. On master the guard reads `oidc_username` instead; the flag was re-keyed before landing (see the banner).'
+services:
+  - api
+techStack:
+  - nodejs
+  - javascript
+  - couchdb
+  - oidc
+tags:
+  - token-login
+  - oidc
+  - authentication
+  - session
+  - login
+  - guard-clause
+related_workflows:
+  - user-registration
+source_pr: medic/cht-core#9901
+source_sha: f74d663dc7e1f9b3b9711237389145699c52dc7e
+distilled_at: '2026-06-22'
+reviewed_by: null
+reviewed_at: null
+confidence: medium
+entities:
+  - api/src/controllers/login.js
+  - shared-libs/user-management/src/token-login.js
+concepts:
+  - one-time token login
+  - OIDC (OpenID Connect) authentication
+  - session issuance
+  - authentication-provider mutual exclusivity
+  - fail-closed guard before session creation
+  - async/await consistency
+related_issues:
+  - cht-core-9735
+stale: true
+---
+
+> **Epic child.** PR #9901 was squash-merged into the feature branch `9735_sso`
+> (`f74d663dc`, 2025-04-23), not into master. That branch reached master as PR #9955
+> (`2cbe9c109`, 2025-06-03). Its own PR number is stamped nowhere on master, which is
+> why this draft's `source_sha` does not resolve in a plain clone. Fetch it with
+> `git fetch origin +refs/pull/9955/head:refs/verify/pr9955` — the epic PR's head ref.
+>
+> **Superseded before landing (`stale-as-written`):** as this PR wrote it, the guard in
+> `getUserByToken` is `user.oidc && config.get().oidc_provider?.client_id` — `oidc` is the
+> per-user truthy flag, `oidc_provider` the app_settings provider config. Inside the epic,
+> PR #9961 (`4b77459de`) replaced the per-user flag with the string `oidc_username` and
+> rewrote the guard as `user.oidc_username && ssoLogin.isSsoLoginEnabled()`
+> (`isSsoLoginEnabled` = `!!config.get('oidc_provider')`, no `client_id` required). That
+> form reached master in `2cbe9c109` and is still in
+> shared-libs/user-management/src/token-login.js on master; the error message and 401
+> status are unchanged.
+
+## Problem
+
+Nothing in the token-login path checked whether the user was an SSO user, so a user flagged `oidc` on their `_users` doc (the per-user flag at this commit) who also held an active token_login could open the token link and be given a session, bypassing the identity provider. SSO users are meant to authenticate through their provider only, so token login was an unintended second way in. The issue asked that `tokenPost` in api/src/controllers/login.js do this check before giving the user a valid session.
+
+## Root Cause
+
+`tokenPost` in api/src/controllers/login.js falls through to `loginByToken` (same file) when the request has no valid session. `loginByToken` calls `tokenLogin.getUserByToken` (shared-libs/user-management/src/token-login.js) to resolve the token to a user id, then `tokenLogin.resetPassword`, creates a CouchDB session and calls `setCookies`. `getUserByToken` validated only that the user's token_login was active, matched the token and had not expired; nothing on the path read the user's `oidc` flag.
+
+## Solution
+
+Added a guard to `getUserByToken` in shared-libs/user-management/src/token-login.js, after the active/match/expiry checks: `if (user.oidc && config.get().oidc_provider?.client_id)` (this commit's form; see the banner) it throws an `Error('Token login not allowed for SSO users')` with `status = 401`. `loginByToken` in api/src/controllers/login.js needs no SSO-specific code: its catch computes `status = err.status || err.code || 400` and `message = err.error || err.message || 'Unexpected error logging in'` and sends `res.status(status).json({ error: message })`, so the client gets a 401 whose `error` field carries the guard's message, and because the rejection comes from the token lookup, `resetPassword` never regenerates the password and no session is created. `loginByToken` was also rewritten from a promise chain to async/await, with the same outcomes.
+
+## Code Patterns
+
+Guard at the lookup step every token login passes through: the SSO check sits in `getUserByToken` (shared-libs/user-management/src/token-login.js) beside the existing `invalid`/`expired` rejections, so its caller `loginByToken` (api/src/controllers/login.js) needs no new branch — it maps any rejection's `status` and `error`/`message` to the response. Promise-chain to async/await normalisation of `loginByToken`.
+
+## Design Choices
+
+The check runs before the token login's side effects — `resetPassword` regenerating the password, the CouchDB session being created, `deactivateTokenLogin` — so nothing is created or changed for an SSO user, rather than issuing a session and revoking it afterwards. At this commit it also requires the app_settings `oidc_provider` to carry a `client_id`, so on an instance with no SSO configured a user flagged `oidc` can still use token login. The issue asked for the check in `tokenPost` (api/src/controllers/login.js); it landed one layer down, in user-management's `getUserByToken`, which `tokenPost` reaches through `loginByToken`.
+
+## Related Files
+
+- api/src/controllers/login.js
+- api/tests/mocha/controllers/login.spec.js
+- shared-libs/user-management/src/token-login.js
+- shared-libs/user-management/test/unit/token-login.spec.js
+- tests/integration/api/controllers/login.spec.js
+
+## Testing
+
+All three spec files are modified, none added; the fixtures below are as written at this PR. api/tests/mocha/controllers/login.spec.js gains 'should reject token login for SSO users' (stubs `getUserByToken` to reject with the 401; asserts status 401 with `error: 'Token login not allowed for SSO users'` and that `resetPassword` is not called). shared-libs/user-management/test/unit/token-login.spec.js gains 'should throw when user is oidc' (`oidc: true` with `oidc_provider.client_id` configured). tests/integration/api/controllers/login.spec.js gains 'should reject token login for SSO users', which configures `oidc_provider.client_id`, creates a token-login user, writes a truthy `oidc` (`'some-provider'`) onto its `_users` doc, opens the token link and asserts the 401 body and an empty `Set-Cookie`. All three cases are still on master, with their fixtures switched from `oidc` to `oidc_username` by PR #9961.
+
+## Related Issues
+
+- #9764: "Update `token_login` flow to not allow login if `oidc_provider` value is set for user." — this draft's issue; it asked for the check in `tokenPost` before a session is issued, keyed on a per-user `oidc_provider`.
+- #9735: "Single sign on (SSO) using identity provider" — the SSO epic this PR is a child of.
+
+## Domain Rationale
+
+**Fit:** strong
+
+The PR modifies the token-based login flow and session-issuance logic to reject users flagged for SSO/OIDC login — this is core authentication/session-management behavior, squarely in the authentication domain.
diff --git a/agent-memory/domains/authentication/issues/9955-feat9735-add-support-for-authenticating-users-via-oidc.md b/agent-memory/domains/authentication/issues/9955-feat9735-add-support-for-authenticating-users-via-oidc.md
new file mode 100644
index 00000000..7d0198c9
--- /dev/null
+++ b/agent-memory/domains/authentication/issues/9955-feat9735-add-support-for-authenticating-users-via-oidc.md
@@ -0,0 +1,152 @@
+---
+id: cht-core-9735
+category: feature
+domain: authentication
+domainFit: strong
+issueNumber: 9735
+issueUrl: https://github.com/medic/cht-core/issues/9735
+title: Add OIDC single sign-on (SSO) authentication support
+lastUpdated: '2026-10-05'
+summary: 'Deployments wanting centralized single sign-on could not authenticate CHT users against an external OIDC/OAuth2 identity provider, since CHT only supported local password and token-login accounts. This PR adds end-to-end OIDC SSO: an oidc_username user property, an ''SSO Email Address'' field in the admin app, login/oidc/authorize and login/oidc endpoints that run the authorization-code flow and set a CouchDB AuthSession cookie, a ''Login with SSO'' button, and guards that keep SSO users out of password login, password reset, token login and the webapp''s update-password option.'
+services:
+  - api
+  - admin
+  - webapp
+techStack:
+  - javascript
+  - nodejs
+  - couchdb
+  - openid-connect
+  - oauth2
+  - angularjs
+tags:
+  - oidc
+  - sso
+  - single-sign-on
+  - authentication
+  - login
+  - oauth2
+  - openid-connect
+  - user-management
+  - couchdb-session
+related_workflows:
+  - user-registration
+source_pr: medic/cht-core#9955
+source_sha: 2cbe9c10991de77e5ed7408432474800ea5185d4
+distilled_at: '2026-06-22'
+reviewed_by: null
+reviewed_at: null
+confidence: medium
+entities:
+  - api/src/services/openid-client.js
+  - api/src/services/sso-login.js
+  - api/src/controllers/login.js
+  - api/src/controllers/users.js
+  - shared-libs/user-management/src/sso-login.js
+  - shared-libs/user-management/src/users.js
+  - shared-libs/user-management/src/token-login.js
+  - admin/src/js/controllers/edit-user.js
+  - ddocs/users-db/users/views/users_by_field/map.js
+  - webapp/src/ts/modules/configuration-user/configuration-user.component.ts
+concepts:
+  - OpenID Connect (OIDC) authentication
+  - single sign-on (SSO)
+  - OAuth2 authorization-code flow
+  - back-channel token exchange (authorization_code -> id_token)
+  - claim-based identity mapping (email claim -> oidc_username)
+  - CouchDB session-cookie generation
+  - external identity-provider integration
+  - mutually-exclusive authentication methods
+related_issues:
+  - cht-core-9736
+  - cht-core-9737
+  - cht-core-9738
+  - cht-core-9760
+  - cht-core-9761
+  - cht-core-9762
+  - cht-core-9763
+  - cht-core-9764
+  - cht-core-9765
+  - cht-core-9766
+  - cht-core-9836
+  - cht-core-9890
+  - cht-core-9907
+  - cht-core-9938
+  - cht-core-9981
+  - cht-core-9983
+  - cht-core-10062
+stale: true
+---
+
+## Problem
+
+Some deployments use a centralized identity system and want users to authenticate through a single sign-on provider rather than maintaining a decentralized set of CHT-local accounts. CHT had no way to authenticate users against an external OIDC/OAuth2 identity provider — it only supported local passwords and token login, with no oidc_username property, no OIDC login endpoints, and no SSO affordances in the UI.
+
+## Root Cause
+
+Missing capability rather than a defect: the authentication flow (login controller, user-management library, and login page) only knew about local Couch credentials and token login. There was no OIDC client, no endpoints to drive the authorization-code flow, no way to associate a user with an external IdP identity, and no server configuration for an OIDC provider.
+
+## Solution
+
+Added full OIDC SSO support across the stack. (1) shared-libs/user-management adds an oidc_username user property on the /api/v?/users endpoints: it cannot be combined with password or token_login, auto-generates a random password, must be globally unique, and requires oidc_provider in app_settings. (2) The admin edit-user modal shows an 'SSO Email Address' field (`user.sso.username`; text input `id="sso-login"` in admin/src/templates/edit_user.html, bound to `oidc_username`) when oidc_provider is configured and token_login is off, hiding the token-login and password inputs when it is set. (3) New API endpoints /medic/login/oidc/authorize (handler `oidcAuthorize`; returns the IdP authorization URL as the body of a 302 response, which the login page's `requestSSOLogin` navigates to) and /medic/login/oidc (handler `oidcLogin`; completes the flow: exchanges the authorization_code for an id_token over a back-channel call with `openid-client`'s `authorizationCodeGrant`, matches the id_token email claim to exactly one user's oidc_username, and sets a CouchDB `AuthSession` cookie that the API computes itself). (4) A 'Login with SSO' button (`id="login-sso"` in api/src/templates/login/index.html) renders on the login page when oidc_provider is configured. (5) Password login, password reset and token login reject users whose `oidc_username` is set while oidc_provider is configured (`isOidcUser` in api/src/controllers/login.js; `getUserByToken` in shared-libs/user-management/src/token-login.js), and setting `oidc_username` mirrors a boolean `oidc_login` onto the user-settings doc, which the webapp's configuration-user component reads to hide the update-password option (`canUpdatePassword`). The users_by_field view is extended to index oidc_username for unique lookups; client_secret is read from the CHT credential `oidc:client-secret`, set via `PUT /api/v1/credentials/:key`.
+
+## Code Patterns
+
+New api/src/services/openid-client.js is a thin re-export of `openid-client`'s `discovery`, `buildAuthorizationUrl`, `authorizationCodeGrant` and `allowInsecureRequests`, so unit tests can stub the ESM dependency; api/src/services/sso-login.js uses it for discovery (`oidc_provider.discovery_url` and `client_id` from app_settings), the authorization URL (`getAuthorizationUrl`, scope `openid email`) and the code exchange (`getIdToken`). SSO session creation lives in api/src/services/sso-login.js: `getCookie` resolves the email claim to a single `_users` doc via `getUsersByOidcUsername` (shared-libs/user-management/src/sso-login.js) and `makeCookie` builds the `AuthSession` value itself — an HMAC-SHA1 over `<username>:<hex epoch seconds>` keyed by `couch_httpd_auth/secret` plus the user's `salt` — instead of posting credentials to `_session`. ddocs/users-db/users/views/users_by_field/map.js is extended to index oidc_username so the email claim can be resolved to a single user. Mutually-exclusive auth-method validation (oidc_username vs password vs token_login) lives in shared-libs/user-management/src/sso-login.js (`validateSsoLogin`, `validateSsoLoginUpdate`), called from `createUser`, `createUsers`, `createMultiFacilityUser` and `updateUser` in shared-libs/user-management/src/users.js.
+
+## Design Choices
+
+The id_token email claim is the join key against the oidc_username user property, so the IdP-asserted email determines the CHT user. OIDC users get an auto-generated random password (and `password_change_required: false`); the resulting `salt` on the `_users` doc is what `getCookie` needs to compute the session cookie (it rejects a user doc without one), while local login is refused by the explicit SSO-user guards on password login, password reset and token login. oidc_username must be unique and requires oidc_provider configured server-side to avoid ambiguous/misconfigured SSO. The post-login app locale comes from the id_token locale claim (when it names an enabled locale; otherwise the first enabled locale) rather than the login-page selection. client_secret is read from the credential store (`secureSettings.getCredentials(OIDC_CLIENT_SECRET_KEY)`, where `OIDC_CLIENT_SECRET_KEY = 'oidc:client-secret'`) rather than from app_settings, so the secret stays out of the `settings` doc, one of the `DEFAULT_DDOCS` every offline user replicates; credentials are stored encrypted in the vault database (`getVaultUrl` in shared-libs/settings/src/index.js). SSO is layered onto the existing CouchDB session-cookie model (issuing an `AuthSession` cookie) rather than replacing it, so all downstream authorization is unchanged.
+
+## Related Files
+
+- api/src/services/openid-client.js (added)
+- api/src/services/sso-login.js (added)
+- api/src/controllers/login.js
+- api/src/controllers/users.js
+- api/src/routing.js
+- api/src/server-utils.js
+- api/src/public/login/script.js
+- api/src/templates/login/index.html
+- shared-libs/user-management/src/sso-login.js (added)
+- shared-libs/user-management/src/users.js
+- shared-libs/user-management/src/token-login.js
+- shared-libs/user-management/src/index.js
+- admin/src/js/controllers/edit-user.js
+- admin/src/templates/edit_user.html
+- ddocs/users-db/users/views/users_by_field/map.js
+- webapp/src/ts/modules/configuration-user/configuration-user.component.ts
+- webapp/src/ts/services/user-settings.service.ts
+- tests/utils/mock-oidc-provider.js (added)
+- tests/e2e/default/login/sso-login.wdio-spec.js (added)
+
+## Testing
+
+New specs: api/tests/mocha/services/sso-login.spec.js, shared-libs/user-management/test/unit/sso-login.spec.js, the e2e spec tests/e2e/default/login/sso-login.wdio-spec.js, and webapp karma specs webapp/tests/karma/ts/modules/configuration-user/configuration-user.component.spec.ts and webapp/tests/karma/ts/services/update-password.service.spec.ts. Updated: mocha specs for the login and users controllers and server-utils; shared-libs/user-management token-login and users specs; admin/tests/unit/controllers/edit-user.spec.js; integration specs for the login and users controllers; the login and users page objects; and several user and contact e2e specs. The integration and e2e tests run against tests/utils/mock-oidc-provider.js (added), a local Express OIDC provider. The specs that use it set `allow_insecure_requests: true` in `oidc_provider` so the provider's plain-HTTP discovery is accepted.
+
+## Related Issues
+
+- #9735: "Single sign on (SSO) using identity provider" — the epic this PR closes (MVP scope); its sub-issues follow
+- #9760: "Update `shared-libs/user-management` to accept an `oidc_provider` property for users" — the issue in this squash's commit subject; delivered by PR #9800 as a boolean `oidc` flag, replaced before landing by `oidc_username` (PR #9961)
+- #9761: "Update user creation frontend to support creating SSO users" — the admin 'SSO Email Address' field (PR #9900)
+- #9762: "Update CHT login page to have button for redirecting to OIDC provider" — the 'Login with SSO' button (PR #9877)
+- #9763: "Update non-SSO login flow to not allow login if `oidc_provider` set for user" — password login and password reset reject SSO users (PR #9887)
+- #9764: "Update `token_login` flow to not allow login if `oidc_provider` value is set for user." — token login rejects SSO users (PR #9901)
+- #9765: "Add support to the CHT api for new endpoint for OIDC login" — the login/oidc/authorize and login/oidc endpoints (PR #9833)
+- #9907: "Handle situation where CHT user does not exist for SSO user" — redirect back to the login page with `sso_error=ssouserinvalid` (PR #9833)
+- #9890: "Ensure proper mapping for SSO users to Couch users" — the email claim to `oidc_username` mapping and the `oidc_login` user-settings flag (PR #9961)
+- #9836: "Disable in-app password change functionality for SSO users" — the webapp hides the update-password option when `oidc_login` is set (PR #9961)
+- #9938: "Require `email` to be provided for user when `oidc = true`" — closed by PR #9961; in the landed design `oidc_username` itself holds the email that the id_token email claim must match
+- #9981: "SSO flow does not support ports with CHT instances not on 443" — fixed on `9735_sso` by commit `15f71f56a`; at this squash the OIDC redirect_uri is built from the configured `app_url` when set, falling back to the request host
+- #9738: "Figure how to run e2e tests" — the SSO e2e spec tests/e2e/default/login/sso-login.wdio-spec.js (PR #9995)
+- #9736: "Choose a Node OIDC library" — research sub-issue; this squash depends on `openid-client`
+- #9737: "Select an Identity Provider service for development" — research sub-issue; no code of its own in this squash
+- #9766: "Update cht-conf to support uploading the SSO config" — cht-conf tooling sub-issue; no code in this squash
+- #10062: "Rendering issue in edit user modal for SSO user" — a later master fix (PR #10153) for a race in the admin edit-user modal, triggered by the extra `/api/v2/users/${$scope.model.name}` request this squash added to load `oidc_username` for users with `oidc_login` set
+- #9983: "Require `app_url` to be set when enabling `token_login`" — a later master change (PR #10004): at this squash the OIDC handlers build their URLs from `serverUtils.getAppUrl(req)`, which falls back to the request host; PR #10004 replaced it with a module-local `getAppUrl()` in api/src/controllers/login.js that throws when `app_url` is unset
+
+## Domain Rationale
+
+**Fit:** strong
+
+The PR implements OIDC single sign-on end to end — login endpoints, the OAuth2 authorization-code flow, and CouchDB session-cookie minting — which is core user authentication. The external identity-provider integration is a means of authenticating users (not health-data interoperability), so authentication is the squarely correct, strong-fit domain.
diff --git a/agent-memory/domains/authentication/issues/9961-feat9890-add-mapping-from-oidc-to-cht-user.md b/agent-memory/domains/authentication/issues/9961-feat9890-add-mapping-from-oidc-to-cht-user.md
new file mode 100644
index 00000000..ce994ea7
--- /dev/null
+++ b/agent-memory/domains/authentication/issues/9961-feat9890-add-mapping-from-oidc-to-cht-user.md
@@ -0,0 +1,136 @@
+---
+id: cht-core-9890
+category: improvement
+domain: authentication
+domainFit: strong
+issueNumber: 9890
+issueUrl: https://github.com/medic/cht-core/issues/9890
+title: Map OIDC/SSO identities to CHT users via oidc_username on _users doc and oidc_login flag on user-settings, hiding password update for SSO users
+lastUpdated: '2026-10-05'
+summary: 'OIDC identities could not be mapped cleanly to CHT users: CHT usernames allow only `[a-z0-9_-]` (so no `@`) while identity providers identify users by email, and the SSO callback matched the id_token `preferred_username` claim to the CHT username. SSO users were also still offered the in-app Update password option. This PR replaces the per-user `oidc` boolean with an `oidc_username` string on the `_users` doc, matched against the id_token `email` claim through the `users_by_field` view, and mirrors a boolean `oidc_login` onto the replicated user-settings doc so the webapp can hide password update, offline included.'
+services:
+  - api
+  - webapp
+techStack:
+  - javascript
+  - typescript
+  - couchdb
+  - angular
+  - oidc
+tags:
+  - oidc
+  - sso
+  - single-sign-on
+  - openid-connect
+  - user-management
+  - microsoft-entra-id
+  - password-management
+  - login
+related_workflows:
+  - user-registration
+source_pr: medic/cht-core#9961
+source_sha: 4b77459dee772ed4da0e08ba78ca21277922a091
+distilled_at: '2026-06-22'
+reviewed_by: null
+reviewed_at: null
+confidence: medium
+entities:
+  - api/src/services/sso-login.js
+  - api/src/controllers/login.js
+  - shared-libs/user-management/src/sso-login.js
+  - shared-libs/user-management/src/users.js
+  - shared-libs/user-management/src/token-login.js
+  - ddocs/users-db/users/views/users_by_field/map.js
+  - webapp/src/ts/modules/configuration-user/configuration-user.component.ts
+  - webapp/src/ts/services/user-settings.service.ts
+concepts:
+  - OIDC/OpenID Connect identity federation
+  - single sign-on (SSO)
+  - separation of auth-sensitive data (_users doc) from non-sensitive data (user-settings doc)
+  - CouchDB user document model and replication boundary
+  - email-as-identity mapping for SSO providers
+  - offline-aware UI gating via replicated user-settings flags
+related_issues:
+  - cht-core-9735
+  - cht-core-9760
+  - cht-core-9762
+  - cht-core-9765
+  - cht-core-9836
+  - cht-core-9938
+stale: true
+---
+
+> **Epic child.** PR #9961 was squash-merged into the feature branch `9735_sso`
+> (`4b77459de`, 2025-05-16), not into master. That branch reached master as PR #9955
+> (`2cbe9c109`, 2025-06-03). Its own PR number is stamped nowhere on master, which is
+> why this draft's `source_sha` does not resolve in a plain clone. Fetch it with
+> `git fetch origin +refs/pull/9955/head:refs/verify/pr9955` — the epic PR's head ref.
+
+## Problem
+
+CHT usernames are restricted to lower-case letters, digits, `_` and `-` (`USERNAME_ALLOWED_CHARS = /^[a-z0-9_-]+$/` in shared-libs/user-management/src/users.js), so they cannot hold an `@`, but OIDC/SSO providers such as Microsoft Entra ID identify users by email (the id_token `email` claim). Before this PR the SSO callback read the id_token `preferred_username` claim and used it directly as the CHT username, so a provider identity could only be mapped when the two happened to match. The per-user state was a boolean `oidc` flag on the `_users` doc, which could not store the mapping email and — because `_users` is not replicated to offline clients — gave the webapp no way to know a user was an SSO user. As a result, the in-app self-serve 'Update password' option was still shown to SSO users, who do not manage their password in CHT.
+
+## Root Cause
+
+OIDC state was modeled as a single boolean `oidc` field on the `_users` doc (added by PR #9800), and the login-time match was `preferred_username` = CHT username, via `getUserSalt` in api/src/services/sso-login.js (removed by this PR). That field could not hold the provider-side identifier, and since the `_users` database does not replicate to the offline webapp, the client UI had no signal to branch on for SSO users (e.g. to hide the password-update option). Nothing required an OIDC user to carry an email to anchor the mapping either.
+
+## Solution
+
+Replaced the boolean `oidc` field with a string `oidc_username` on the `_users` doc — `'oidc'` becomes `'oidc_username'` in `USER_EDITABLE_FIELDS`, and in `missingFields` a user with `oidc_username` needs no password (shared-libs/user-management/src/users.js) — and made the provider's email the mapping key:
+
+- ddocs/users-db/users/views/users_by_field/map.js now lists `'oidc_username'` beside `'contact_id'` among the properties it emits as `[property, doc[property]]`. shared-libs/user-management/src/sso-login.js gains `getUsersByOidcUsername` (a `users/users_by_field` query) and a uniqueness check in `validateSsoLogin` (`The oidc_username [...] already exists for user [...]`); `isSsoLoginEnabled` becomes a zero-argument `!!config.get('oidc_provider')`. Both are exported to the API through a new `ssoLogin` object in shared-libs/user-management/src/index.js.
+- In api/src/services/sso-login.js, `getIdToken` reads the `email` claim instead of `preferred_username`, throwing `Email claim is missing in the id token.` when it is absent, and `getCookie` resolves the CHT user with `getUsersByOidcUsername` — a 401 when none matches, an error when more than one does — replacing the `getUserSalt` lookup, which PR #9833 had added.
+- `getSettingsUpdates` in shared-libs/user-management/src/users.js sets `oidc_login = !!data.oidc_username` on the user-settings doc whenever an update carries `oidc_username`. webapp/src/ts/modules/configuration-user/configuration-user.component.ts now computes `canUpdatePassword = !user.token_login && !user.oidc_login && !this.sessionService.isAdmin()`, and the `UserSettings` interface in webapp/src/ts/services/user-settings.service.ts gains `oidc_login?: boolean`.
+- api/src/controllers/login.js (`isOidcUser`) and shared-libs/user-management/src/token-login.js (`getUserByToken`) switch their SSO checks to `oidc_username && ssoLogin.isSsoLoginEnabled()`, and `renderLogin` uses `ssoLogin.isSsoLoginEnabled()` in place of `hasOidcProvider`, which is removed from api/src/services/settings.js.
+
+## Code Patterns
+
+Dual-doc auth pattern: keep the auth-sensitive identifier on the `_users` doc and mirror a non-sensitive boolean onto the replicated user-settings doc so offline clients can branch on it. Here the mirror is written by `getSettingsUpdates` in shared-libs/user-management/src/users.js (`settings.oidc_login = !!data.oidc_username`) — the same split shared-libs/user-management/src/token-login.js already uses for `token_login`, which it writes to both `user` and `userSettings`. View-backed identity lookup: a `users_by_field` key `['oidc_username', value]` plus `getUsersByOidcUsername` serves both the login-time match and the create/update-time uniqueness check. UI gating on the replicated flag: `canUpdatePassword` in webapp/src/ts/modules/configuration-user/configuration-user.component.ts reads `oidc_login` from the user-settings doc that `UserSettingsService` returns.
+
+## Design Choices
+
+The data is deliberately split because the `_users` database is not replicated to offline clients: `oidc_username` (the sensitive mapping key) stays on `_users`, while `oidc_login` (a non-sensitive flag) goes on the replicated `user-settings` doc so the webapp can drive UI without exposing auth data — the convention token_login already used. Email is the mapping key because CHT usernames cannot contain `@` while OIDC providers identify users by email. Issue #9938 proposed requiring a separate `email` on users with `oidc = true`; instead the email is the `oidc_username` value itself, which must be unique, and a login whose id_token has no `email` claim is refused. The issue scoped this as an MVP targeting Microsoft Entra ID.
+
+## Related Files
+
+- api/src/controllers/login.js
+- api/src/services/settings.js
+- api/src/services/sso-login.js
+- api/tests/mocha/controllers/login.spec.js
+- api/tests/mocha/services/sso-login.spec.js
+- ddocs/users-db/users/views/users_by_field/map.js
+- shared-libs/user-management/src/index.js
+- shared-libs/user-management/src/sso-login.js
+- shared-libs/user-management/src/token-login.js
+- shared-libs/user-management/src/users.js
+- shared-libs/user-management/test/unit/sso-login.spec.js
+- shared-libs/user-management/test/unit/token-login.spec.js
+- shared-libs/user-management/test/unit/users.spec.js
+- tests/integration/api/controllers/login.spec.js
+- tests/integration/api/controllers/users.spec.js
+- tests/utils/mock-oidc-provider.js
+- webapp/src/ts/modules/configuration-user/configuration-user.component.ts
+- webapp/src/ts/services/user-settings.service.ts
+- webapp/tests/karma/karma-unit.base.conf.js
+- webapp/tests/karma/ts/modules/configuration-user/configuration-user.component.spec.ts (added)
+- webapp/tests/karma/ts/services/update-password.service.spec.ts (added)
+
+## Testing
+
+Updated: the api mocha specs api/tests/mocha/controllers/login.spec.js (rewrites 'should return 400 if is SSO User', which previously asserted `password-short`, to assert `Password Reset Not Permitted For SSO Users`) and api/tests/mocha/services/sso-login.spec.js (e.g. 'throws error if email claim not returned', 'throws error if multiple users are found for oidc_username'), and the shared-libs/user-management unit specs (sso-login, token-login, users). Added: two webapp karma specs, webapp/tests/karma/ts/modules/configuration-user/configuration-user.component.spec.ts and webapp/tests/karma/ts/services/update-password.service.spec.ts; webapp/tests/karma/karma-unit.base.conf.js lowers its `functions` coverage threshold from 86 to 85. Integration specs tests/integration/api/controllers/login.spec.js and tests/integration/api/controllers/users.spec.js are updated (the latter adds 'should fail to create/update a user when oidc_username is a duplicate', retitled 'should fail to create a user when oidc_username is a duplicate' by PR #9900 before landing); the login spec runs against tests/utils/mock-oidc-provider.js, whose id_token now carries an `email` claim.
+
+## Related Issues
+
+- #9890: "Ensure proper mapping for SSO users to Couch users" — this draft's issue; usernames cannot contain `@` while SSO providers identify users by email, scoped to an MVP for Microsoft Entra ID.
+- #9836: "Disable in-app password change functionality for SSO users" — addressed here by `oidc_login` gating `canUpdatePassword`.
+- #9938: "Require `email` to be provided for user when `oidc = true`" — the PR body says "Closes #9938"; superseded by making the email the `oidc_username` value and refusing id_tokens without an `email` claim.
+- #9735: "Single sign on (SSO) using identity provider" — the SSO epic this PR is a child of.
+- #9760: "Update `shared-libs/user-management` to accept an `oidc_provider` property for users" — delivered by PR #9800 as the boolean `oidc` flag that this PR replaces with `oidc_username`.
+- #9762: "Update CHT login page to have button for redirecting to OIDC provider" — delivered by PR #9877 with the `settings.hasOidcProvider()` helper that this PR removes in favour of `ssoLogin.isSsoLoginEnabled()`
+- #9765: "Add support to the CHT api for new endpoint for OIDC login" — delivered by PR #9833, which added api/src/services/sso-login.js with the `preferred_username` lookup (`getUserSalt`) that this PR replaces with the `email` claim matched against `oidc_username`.
+
+## Domain Rationale
+
+**Fit:** strong
+
+The PR is entirely about OIDC/SSO login — mapping an external OIDC identity to a CHT user, storing auth-sensitive login data, and gating the in-app password-change affordance for SSO users. Identity federation and login/credential management are squarely the authentication domain.
diff --git a/agent-memory/schema.json b/agent-memory/schema.json
index 071dccf7..34c5adc7 100644
--- a/agent-memory/schema.json
+++ b/agent-memory/schema.json
@@ -138,6 +138,15 @@
           "pattern": "^medic/(cht-core|cht-interoperability)#[1-9][0-9]*$",
           "description": "Source PR reference, format: medic/<repo>#<number>"
         },
+        "source_prs": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^medic/(cht-core|cht-interoperability)#[1-9][0-9]*$"
+          },
+          "minItems": 1,
+          "description": "All PR refs that resolve to this issue (backport cherry-picks, multi-PR epics), set by the dedup pass when more than one draft collapsed into this one. source_pr remains the canonical PR."
+        },
         "source_sha": {
           "type": "string",
           "pattern": "^[0-9a-f]{7,40}$",