Patriot Platform Members 0.4.9 — Matrix member access
Prepared 17 October 2026

STATUS
Code and simulated access-control tests passed. This is not yet a live-tested
integration. Install the update, configure it, and run the pilot checklist below
before directing members to it. Existing registration, agreement, certificate,
email and page code is retained. Chat starts disabled until credentials exist.

WHAT MEMBERS GET
My membership now includes chat setup for members whose verified email and
accepted signed agreement pass the existing PPM_Agreement::active check.
Members choose a separate chat password after confirming their current website
password. WordPress passwords are not copied into Matrix. Chat passwords are
sent to Synapse over VPS loopback and not stored by this module or emailed.
The generated Matrix ID is permanent and displayed on My membership.
This is account provisioning and room access management, NOT single sign-on.
There is no additional chat invitation email; setup is available in My membership.
Use [patriot_chat] if a separate WordPress setup page is desired.

CONNECTION
The WordPress site and Synapse must run on the same VPS.
Private API: http://127.0.0.1:8008
Public chat: https://chat.patriotplatform.earth
Matrix server identity: patriotplatform.earth

Create a dedicated Synapse administrator service account, e.g. ppm-bridge,
using the existing register_new_matrix_user procedure. Generate its access token
privately on the VPS and define PPM_MATRIX_ADMIN_TOKEN server-side in wp-config.php
(or load it from a protected PHP file outside public_html).
Do not paste the token into chat, email, screenshots or WordPress pages.
This is a powerful Synapse administrator token. A compromise of the WordPress
account can expose it; it is not a narrowly scoped invite-only credential.
Do not use Mike's personal Element session token.
Do not expose /_synapse/admin through the public Apache proxy.
A site copy or staging restore must NOT load the production token.

INSTALL AND CONFIGURE
1. Keep a fresh WordPress database/files backup and the previous plugin ZIP.
2. WordPress > Plugins > Add New Plugin > Upload Plugin: upload this ZIP and
   choose Replace current with uploaded. The plugin folder/name is unchanged.
3. Open Patriot Platform > Member chat. It should say Not configured initially.
4. Configure the dedicated service credential privately on the VPS.
5. Click Test connection. Failure is reported without exposing server bodies.
6. Create production rooms in Element for Australia-wide members, each required
   region, and approved coordinators. Keep pilot rooms separate.
7. Each room must be encrypted, invite-only, and history visible since joining.
   Restrict invitations to administrators. Add the service account, have it join,
   and make it a room administrator. No room power is silently elevated by code.
8. Paste raw room IDs beginning with ! into Member chat settings. A different
   room is required for each scope. Empty scopes are allowed for phased rollout.
   Configure at least the national room and the first pilot member's region.
9. Validate and save rooms. Public, unencrypted and incorrectly restricted rooms
   fail validation. Current room settings must remain restricted afterwards.
10. Use a real server cron to run WordPress scheduled events reliably. The module
    schedules a five-minute event, processing 10 linked accounts per run with
    pagination. A complete sweep takes longer as membership grows. Membership
    updates also trigger sync at request shutdown. Monitor last run and results.
11. Link Member Chat to the setup page/My membership for onboarding, or retain
    the direct Element menu link with a separate setup link on the membership page.

ACCESS AND LIMITATIONS
- Only bridge-created accounts are managed. Existing mikeh and pilot-test accounts
  remain manual; never replace their metadata to force-link them.
- Active members get national and own-region invitations; approved/qualified
  coordinators also get the coordinators room. They accept invitations in Element.
- Ordinary members are never made Matrix server administrators. Coordinator status
  gives room access, not room moderation power or server administration.
- Removed entitlements are banned in previously managed rooms. A membership
  suspension/resignation or invalid agreement locks the managed Matrix account.
- Room reassignment locks first and unlocks only after access changes succeed.
- Restored membership can remove bans applied by the bridge. Manual bans and
  manually locked/deactivated accounts are left for administrator review.
- WordPress user deletion queues an ownership-checked account lock. Failed locks
  are retried via the scheduled task using minimal retained identity records.
- Network failures or scheduler failure can delay revocation. Check status and
  manually lock the Matrix account during an outage if immediate removal is needed.
- A crashed operation deliberately leaves a lock option ppm_chat_lock_USERID.
  Investigate and ensure no worker is running before clearing that specific option.
- Existing downloaded/encrypted messages cannot be recalled by removing access.
- Resetting a chat password logs out devices. Save Element's recovery key first.
  Password reset does not restore encryption keys or old encrypted message history.
- Matrix registration remains closed. This module does not enable guest access.
- Members who decline/leave an entitled room can be re-invited during sync.
- Do not disable the plugin or remove the token while relying on automatic access
  removal. In an emergency, manually lock managed accounts before disabling.
- Room creation, token configuration, room mapping and server cron are deployment
  tasks; uploading this ZIP alone does not complete them.

PILOT ACCEPTANCE CHECKLIST
Use a disposable WordPress membership and controlled test email address.
[ ] Pending/unverified member cannot create a chat account.
[ ] Approved verified member sets chat password and signs in to Element.
[ ] National and own-region invitations appear and encrypted messages work.
[ ] Unrelated region and coordinators room are inaccessible to ordinary member.
[ ] Coordinator approval grants only the intended coordinator-room invitation.
[ ] Coordinator revocation removes that room's access.
[ ] Region change removes old room and invites new room.
[ ] Suspension blocks an already signed-in chat session, not just new logins.
[ ] Restoration restores access without duplicating the account.
[ ] Manual room ban and manual account lock remain respected.
[ ] Retry after a connection failure reports status and does not duplicate accounts.
[ ] WordPress deletion locks the managed account; pilot admin remains untouched.
[ ] Scheduled sync advances and failed operations are visible in Member chat.
[ ] Registration confirmation and certificate delivery still pass separately.

LOCAL VALIDATION
PHP 8.3 syntax checks across plugin PHP files.
19 simulated behavioral assertions: pending rejection; provisioning; ordinary
account privileges; region isolation; idempotence; ownership mismatch; admin
account protection; failed removal locking; error redaction; retry; coordinator
approval/revocation; suspension/restoration; manual lock/ban; concurrency; deletion
retry and deletion lock. Simulation is not a substitute for the live pilot.

REFERENCES
https://element-hq.github.io/synapse/latest/admin_api/user_admin_api.html
https://element-hq.github.io/synapse/latest/admin_api/register_api.html
https://spec.matrix.org/latest/client-server-api/
