From 32b4fecb87ae2ef2ae61d29bde5e6d2dfb805bac Mon Sep 17 00:00:00 2001 From: Mud <44410798+MudDev@users.noreply.github.com> Date: Tue, 19 May 2026 09:35:31 -0600 Subject: [PATCH] docs(multiuser): add README documenting the plugin and its CLI flags The Multiuser plugin (public-gateway / multi-user proxy mode) has no documentation. Operators turning it on hit several rough edges: - `--multiuser-no-new-sites` is a store_true flag; people pass values like `enabled` which argparse silently ignores. - Without `--multiuser-local`, the local operator becomes a regular proxy user and hits "This function (...) is disabled on this proxy!" on admin-only actions. - The newer `NoNewSites` plugin overlaps in purpose but isn't cross-referenced anywhere. Add a README covering: when to enable the plugin, both CLI flags with correct semantics (default values, boolean nature, conf-file form), the admin vs. proxy-user distinction, how to log in as an existing master address, and a pointer to NoNewSites as the simpler alternative. Credit: @mx5kevin (PR #42) flagged that the plugin needed documentation. --- plugins/disabled-Multiuser/README.md | 124 +++++++++++++++++++++++++++ 1 file changed, 124 insertions(+) create mode 100644 plugins/disabled-Multiuser/README.md diff --git a/plugins/disabled-Multiuser/README.md b/plugins/disabled-Multiuser/README.md new file mode 100644 index 000000000..2ca0620e4 --- /dev/null +++ b/plugins/disabled-Multiuser/README.md @@ -0,0 +1,124 @@ +# Multiuser Plugin + +Turns an EpixNet instance into a multi-user proxy gateway. Each visitor is +assigned a cookie-backed identity automatically; admins log in with their +existing master seed. + +By default this plugin is **disabled** (the directory is named +`disabled-Multiuser`). Enable it only if you are deliberately running a +public gateway. For normal desktop use, leave it disabled. + +## Enabling the plugin + +Rename the directory so the plugin manager loads it: + +```bash +mv plugins/disabled-Multiuser plugins/Multiuser +``` + +Restart EpixNet. The plugin will register two new CLI flags +(`--multiuser-local`, `--multiuser-no-new-sites`). + +To disable again, rename back to `plugins/disabled-Multiuser`. + +## Operating modes + +The plugin's behaviour for any given request depends on whether the visitor +is a **proxy user** (cookie-backed anonymous identity) or an **admin**. +Admin status is granted to: + +- Any visitor whose `master_address` cookie matches an entry in + `/private/users.json` (the local user file, populated by your + own client), **or** +- All visitors, if `--multiuser-local` is passed. + +Proxy users have access to most browsing features but are blocked from +admin-only actions (decorated with `@flag.no_multiuser` in the source). +Attempts produce the notification: + +```text +This function () is disabled on this proxy! +``` + +## CLI flags + +### `--multiuser-local` + +Run the plugin in **local mode**: every visitor is treated as an admin and +user objects are persisted to disk. Use this when you want the multi-user +UI features (login form, user-switching, master-seed prompts) on your own +machine without locking yourself out of admin functions. + +```bash +python3 epixnet.py --multiuser-local +``` + +Do not use this in production. The flag's own help text describes it as +"unsafe Ui functions". + +### `--multiuser-no-new-sites` + +Block proxy users from adding sites the gateway hasn't already loaded. +Admins (per the rules above) can still add sites. + +```bash +python3 epixnet.py --multiuser-no-new-sites +``` + +The flag is a boolean (`store_true`). It is **off by default** — adding +new sites is allowed unless you pass this flag. Passing the flag without a +value is correct; do not pass `enabled`, `true`, `1`, etc. + +When the flag is on and a proxy user visits an unknown site address, the +gateway returns: + +```text +Not Found +Adding new sites disabled on this proxy +``` + +The flag can also be set persistently in `epixnet.conf`: + +```ini +[global] +multiuser_no_new_sites = True +``` + +### Combining the flags + +For a public gateway where you (the operator) want to keep admin rights: + +```bash +python3 epixnet.py --multiuser-local --multiuser-no-new-sites +``` + +This locks down site-adding for anonymous visitors while letting you add +and manage sites normally. + +## Logging in as an existing master address + +If you want to use your existing master seed (so you appear as admin via +`users.json` rather than via `--multiuser-local`), Multiuser exposes a +`userLoginForm` websocket action. The simplest way to invoke it from a +clean session: + +1. Clear the `master_address` cookie for your EpixNet origin, or open the + dashboard in a private window. +2. In the browser's JavaScript console (with the dashboard frame focused), + run: + ```js + epixframe.cmd("userLoginForm") + ``` +3. Paste the master seed from `/private/users.json` into the + prompt and submit. The cookie is updated and the page reloads. + +Some site UIs (e.g. Epix Talk) surface a "Connect xID" / Login button +that calls the same action — once that flow is invoked you can paste the +seed there instead of using the console. + +## Related + +- `NoNewSites` plugin (`plugins/disabled-NoNewSites/`) is a newer, simpler + way to lock down a public gateway. It also injects a "Public gateway — + read-only" banner. If you only need to block site additions and don't + want the full multi-user account system, enable `NoNewSites` instead.