rpg-ui is a read-only browser for folder-backed RPG worlds. One Rust/axum
process serves the embedded Vue application and reads the configured world
directly from disk. Derived office previews are kept in a separate cache.
- Without
--config(local mode) the HTTP listener accepts loopback addresses only and the implicit userlocalis a game master. A non-loopback address requires an authentication module (see *Authentication and sharing). - The world root is never written. Characters, grants and sessions live in the application state directory, which is refused inside the world. Canonical path checks reject traversal, excluded components, and symlinks that escape the root.
.git, Emacs lock files, and office lock files are excluded.- Source HTML is never rendered directly. HTML, Markdown, and Org previews are sanitized; active and externally loaded content is removed.
- Unknown originals download as attachments. Images and PDFs use inline MIME
responses with
nosniffand a restrictive sandbox policy. - DOC extraction runs
catdocon a temporary copy under Landlock, network seccomp,no_new_privs, an 8 MiB output limit, and a bounded timeout. ODT and SXW previews parse boundedcontent.xmldirectly; scripts and macros are ignored rather than interpreted. Only extracted plain text is served.
Requires Rust and Node.js/npm; Cargo fetches the patched orgize pinned in
Cargo.toml. Legacy DOC previews additionally require /usr/bin/catdoc and
Linux Landlock/seccomp support. ODT/SXW extraction needs no office suite.
The frontend build is an explicit prerequisite for a release build. The Rust build script never runs npm itself.
npm --prefix frontend ci
npm --prefix frontend run build
cargo build --releaseDebug builds and Rust tests use a generated shell under Cargo’s OUT_DIR when
frontend/dist is absent; no placeholder frontend asset is committed.
rpg-ui --serve \
--root "/absolute/path/to/world" \
--addr 127.0.0.1:0 \
--cache-dir "$HOME/.cache/rpg-ui" \
[--state-dir PATH] [--config rpg-ui.yml]The default address is 127.0.0.1:0, allowing the operating system to choose a
free port. --state-dir holds rpg-ui.sqlite and defaults to
$XDG_STATE_HOME/rpg-ui/<first 16 hex digits of sha256(canonical root)>
(XDG_STATE_HOME falls back to ~~/.local/state~). Use -v, -vv, or -vvv for progressively more logging. Component
filters use --log TARGET:LEVEL, and --log-time adds timestamps.
rpg-ui has two modes:
- Local mode (no
--config): loopback only, no login, full game-master access; the game master may still view the world as any character. - Authenticated mode (
--config): any bind address. Everyapi/*route exceptGET~/~POST api/sessionanswers 401login-requiredwithout a session. Static assets stay public. Run it behind an HTTPS reverse proxy that setsX-Forwarded-Proto: httpsso the session cookie is markedSecure.
The configuration is dash-cased YAML; unknown keys, an unknown module or a missing required key stop the server at startup:
auth:
module: ldap
ldap:
url: ldap://ldap:389 # ldap:// or ldaps://
bind-dn: cn=reader,dc=example,dc=com # optional, with bind-password
bind-password: secret
search-base: ou=users,dc=example,dc=com
search-filter: "(objectClass=person)"
user-id-field: uid
admin-group: cn=gm,ou=groups,dc=example,dc=com # optional
game-masters: [vaab] # optional logins with game-master rightsThe LDAP module binds as bind-dn (or, when bind-dn and bind-password
are both omitted, searches anonymously), searches search-base for exactly one
entry matching (&<search-filter>(<user-id-field>=<escaped login>)), then binds
as that entry with the password. Empty passwords are refused before any bind.
The directory is only read. A user is a game master when they belong to
admin-group (member, uniqueMember or memberUid) or are listed in
game-masters. The login used by rpg-ui is the directory’s own spelling of
user-id-field.
The local authentication module uses accounts in the application’s SQLite
state. It is not no-config local mode: users must log in. Passwords are stored
only as salted Argon2id hashes (default parameters), never in plaintext.
auth:
module: local
game-masters: [glouk]The optional auth.local: {} section has no keys. Do not include an auth.ldap
section for this module. Logins are exact/case-sensitive; configured
game-masters promotes them as it does for LDAP.
Bootstrap the first account offline, using the same root/state directory that the server will use. The password is read from stdin, not an argument:
read -rs -p 'Initial password: ' password; printf '\n' >&2
printf '%s\n' "$password" | rpg-ui --root /absolute/path/to/world \
--state-dir "$HOME/rpg-ui/state" --set-password glouk --display-name Glouk
unset password
rpg-ui --serve --root /absolute/path/to/world --addr 127.0.0.1:8081 \
--state-dir "$HOME/rpg-ui/state" --config "$HOME/rpg-ui/rpg-ui.yml"--set-password LOGIN creates or resets an account and exits without serving;
--serve cannot be combined with it. It reads only the first line (LF/CRLF
removed, spaces retained); empty input and passwords over 1024 UTF-8 bytes are
refused. --root remains required; without --state-dir, the same world-scoped
default applies. --config is unnecessary for this offline action. A reset
invalidates all sessions and preserves the display name unless --display-name
is supplied. Neither world documents nor the preview cache are touched.
Game masters get a Users panel to list/add/remove accounts. Removing a user
ends their sessions and unassigns their characters without deleting characters
or grants. A game master cannot delete their own account. Every logged-in local
user can change their own password after supplying the current password; the
current session remains and other sessions end. LDAP/no-config mode offer
neither account administration nor password changes. See doc/api.md for
validation limits and API status codes.
Sessions are a random 256-bit token in the rpg-ui-session cookie
(HttpOnly; SameSite=Strict; Path=/); only its SHA-256 is stored. They expire
after 30 days of inactivity and survive restarts. Failed logins are answered
after a fixed delay. Mutating requests must send Content-Type:
application/json (a request without a body may omit it).
Read access is granted to characters, never to users. Game masters create characters, assign their owner and grant files or folders; a folder grant also covers files added to it later. A player selects one of their characters (or claims an unowned one) and then sees only what it may read, plus the folders leading to it. Unreadable documents answer 404 exactly like missing ones; search and live updates are filtered on the server.
The sharing matrix starts with an “Everyone” column, and the Share panel offers the same option. These common grants apply to all characters, including newly created ones, and folder grants cover later files. Character cells covered by a common grant show “via Everyone”; common grants survive character deletion and cannot be excluded per character.
Operators may also edit data in rpg-ui.sqlite through another SQLite
connection. The server polls PRAGMA data_version on its own connection every
second and republishes filtered snapshots after external commits, so open tabs
update within roughly 1–2 seconds. Server-owned writes do not trigger this
poller. Store alone creates and migrates the schema.
All resource paths are world-relative and all errors are non-2xx JSON objects
with an error field and a stable code. See doc/api.md for the complete
contract, including sessions, characters and grants.
GET api/world— world basename.GET api/tree— current flat directory/file tree plus warnings.GET api/archive/events?sub=...— root-confined filesystem change stream;api/treeregisters akal-ssesubscription before reading the snapshot.GET api/document?path=...— current safe preview.GET api/file?path=...— original bytes under the safe disposition policy.GET api/search?q=...— names, readable text, and already cached office text.
Search deliberately does not convert every office document. Its response warns when office content is not yet cached, so filename-only coverage is explicit. One recursive notify watcher publishes debounced write-only updates. The browser resnapshots before reconnecting, retains its last good view on a failure, and updates the current document and open search without a manual refresh button.
Application-authored text uses vue3-gettext. World filenames, titles, snippets
and file content are never translated. To refresh the English source catalog
after editing a UI message:
npm --prefix frontend run gettext:extract
npm --prefix frontend run gettext:compileThe extraction source is frontend/src/language/messages.pot. There is no
French catalog in this delivery; new translations may be added as PO files.
npm --prefix frontend test
npm --prefix frontend run build
cargo fmt --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test
bin/test-scripts
cargo build --releasebin/test-scripts runs the sunit tests of the bin/ scripts (tests/scripts/).
The real-office integration test runs only when RPG_UI_TEST_WORLD names a
read-only world holding the sample documents listed in
tests/real_office_contract.rs; otherwise it is skipped. It copies those
documents to a scratch world before conversion.
The LDAP integration test runs only when RPG_UI_TEST_LDAP_URL names a
disposable directory, since it recreates ou=rpg-ui-test there:
docker run -d --rm --name rpg-ui-ldap-test -p 127.0.0.1:3389:389 \
-e LDAP_DOMAIN=rpg.test -e LDAP_ADMIN_PASSWORD=admin-secret \
osixia/openldap:1.5.0
RPG_UI_TEST_LDAP_URL=ldap://127.0.0.1:3389 cargo test --test ldap_contract
docker stop rpg-ui-ldap-testRequests and assets use relative URLs and navigation uses hash routing, so the interface works unchanged when a reverse proxy mounts it under a path prefix. rpg-ui never supervises itself: whatever starts it owns the process.
bin/sync-world mirrors the contents of a local world to a directory on a
server over SSH. Its three locations are required:
bin/sync-world --source /home/user/world/src --host root@host.example \
--dest /srv/rpg-ui/world [--dry-run] [--coalesce [--delay SECONDS]]The remote copy is a mirror: destination-only files are deleted, so the
destination must be dedicated to it. --dry-run shows the plan. --coalesce
is meant for file-change hooks: a burst of changes waits --delay seconds (5
by default) and gives one rsync, and a change made while a mirror is running is
included by that mirror running once more; two rsyncs never run at the same
time.
Read grants are stored on paths: moving a shared file or folder in the world drops its grant.
- Office previews are labelled plain-text extracts; original layout, images, comments, and tracked changes are not reproduced.
- Search includes office contents only after that exact content fingerprint has been previewed. It is not a complete office index.
- The legacy text fallback is Windows-1252. Other historical encodings are not auto-detected.
- PDF documents are read in page with the shared
@0k/pdf-viewer(page navigation, zoom, pinch/pan); large scans are range-loaded page by page once the server honoursRangerequests, which is not yet the case. Unsupported binary formats offer source downloads rather than embedded previews. DOCX is not yet an extraction format. - Local mode gives full GM access to every process that can reach loopback. There is no document editing in either mode.
- A character never receives archive-wide tree or search warnings, since they may name entries it cannot read.