Skip to content
0kPublic

About

Read-only browser for folder-backed RPG worlds

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

22 Commits

Folders and files

Repository files navigation

rpg-ui

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.

Safety model

  • Without --config (local mode) the HTTP listener accepts loopback addresses only and the implicit user local is 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 nosniff and a restrictive sandbox policy.
  • DOC extraction runs catdoc on a temporary copy under Landlock, network seccomp, no_new_privs, an 8 MiB output limit, and a bounded timeout. ODT and SXW previews parse bounded content.xml directly; scripts and macros are ignored rather than interpreted. Only extracted plain text is served.

Build

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 --release

Debug builds and Rust tests use a generated shell under Cargo’s OUT_DIR when frontend/dist is absent; no placeholder frontend asset is committed.

Run

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.

Authentication and sharing

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. Every api/* route except GET~/~POST api/session answers 401 login-required without a session. Static assets stay public. Run it behind an HTTPS reverse proxy that sets X-Forwarded-Proto: https so the session cookie is marked Secure.

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 rights

The 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.

Local accounts

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.

HTTP API

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/tree registers a kal-sse subscription 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.

English interface and catalogs

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:compile

The extraction source is frontend/src/language/messages.pot. There is no French catalog in this delivery; new translations may be added as PO files.

Verification

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 --release

bin/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-test

Running behind a reverse proxy

Requests 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.

Publishing a world to a server

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.

Known limitations

  • 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 honours Range requests, 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.

About

Read-only browser for folder-backed RPG worlds

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages