wtclaude
b30e82cde2
The consumer half of a release module-uo's CI has been publishing since
phase 3 closed. Before this, core had the installed_modules provenance
columns and no code that could ever fill them: nothing fetched, verified,
unpacked, removed or purged anything, and there was no admin route at all.
Adds modules/archive.js, modules/install.js, schema.runPurge(),
lifecycle.stop(), loader.stopHook(), and /api/v1/admin/modules with eight
routes. 797 server tests (+76), manifest 158 -> 166 + 2 internal, OpenAPI
gains 8 operations and loses nothing.
Reject, never sanitise
----------------------
The download is the easy part: an https-only allowlist re-checked on every
redirect hop, a declared sha256 compared against the bytes that arrived, and
a byte cap. Unpacking is where the archive chooses the filenames, and core
writes into a directory bind-mounted from the host, so an escape is not
confined to the container.
archive.js inspects the whole archive before a byte is unpacked and refuses
absolute and drive-absolute paths, `..` segments, NUL bytes, backslashes,
anything that is not a regular file or a directory, more than one top-level
entry, and anything over the entry or byte caps. Refusing symlinks and
hardlinks outright is what keeps this off the majority of node-tar's
published advisories rather than depending on the library to contain them.
That two-pass shape is load-bearing, and it was measured rather than assumed:
extracting an archive whose fourth member escapes upward throws under
node-tar 7.5.22 -- and leaves the first three members on disk. The loader
scans that directory at require time on the next boot, so a half-unpacked
module is a module. Everything therefore happens in a scratch directory that
is removed on any failure, and the move into place is the last step.
`tar` is pinned to ^7.5.22 rather than the ^6 that installs by default: 6.x
is flagged critical, and reading the advisory list is what the file's header
now says out loud -- almost all of it is hardlink or symlink traversal and
PAX header interpretation differentials, which is exactly this feature's
threat model.
Two things the plan had wrong
-----------------------------
The bundle's top-level directory is `module-uo-<version>`, not the module id
-- so "the top-level name must equal the id" was checked against nothing real.
The extractor strips that level instead, because its name belongs to whoever
published the bundle and the directory it lands in is core's. What is checked
instead is the unpacked module.json: a manifest promising `uo` and delivering
something else is refused rather than installed under the name it promised.
And purge cannot be a follow-up action (decision 5): purge.sql lives inside
the directory uninstall deletes. It is offered in the uninstall flow and as a
standalone action on a still-installed module, and the standalone one refuses
unless the module is already disabled -- dropping tables under something that
is still serving leaves it answering out of a world that no longer exists.
Disable now means stopped
-------------------------
lifecycle.stop() dispatches that one module's onShutdown before flipping the
guard, so a module an operator switches off actually releases its sockets and
closes its streams instead of merely becoming unreachable. The hook runs
first and the state moves after it, because while onShutdown runs the module
is still `started` and that is the only state in which its routes and the
world it is tearing down agree. A hook that throws does not stop the disable
-- the opposite of the boot path's rule, and deliberately.
Enable is not its mirror and there is no start(id) beside it. There is no
onBoot re-dispatch and the hooks were never promised re-entrant, so enable
moves the row and the restart route starts it. A test pins that enable does
not touch the loader, because "fixing" it is a one-line change that would put
a module with closed sockets back on the nav.
Restart raises SIGTERM against its own process rather than calling the
shutdown path directly, so server.js's handler stays the one graceful-shutdown
path and this route cannot drift from it.
The allowlist bootstraps from MODULE_SOURCE_HOSTS into a settings row and is
admin-managed after that (decision 6); seedDefault is INSERT IGNORE, so
changing the variable on an existing deployment is a no-op by design. An empty
list forbids every install rather than allowing every host -- the safe
direction for a value someone might blank by accident.
Verified against the real v0.3.0 release
----------------------------------------
Not a fixture: fetched the published install manifest over the real Gitea
host and its redirect chain, verified the sha256, inspected and unpacked the
252,517-byte artifact to 82 files, and then booted core against the result --
the module registered its five mounts, seven streams and eight capabilities
and resolved its client chunk, with no scratch directory left behind.
Two defects this slice's own tooling caught, both of which had already been
written down as classes:
- the controller destructured runPurge at require time, capturing the
function rather than the module, which made the one dependency whose
ORDER matters the one that could not be substituted;
- two swagger annotations carried an apostrophe inside a quoted string,
dropped silently by swagger-autogen before slice 5 taught it to fail loudly.
Co-Authored-By: Claude <noreply@anthropic.com>
148 lines
7.7 KiB
Plaintext
148 lines
7.7 KiB
Plaintext
# ─── Runic Gateway server — local dev environment ───
|
|
# Copy to server/.env for running `npm run dev` outside Docker.
|
|
# (In Docker, the root .env / docker-compose provides these instead.)
|
|
|
|
NODE_ENV=development
|
|
PORT=3000
|
|
# Separate, unpublished port for server<->bot internal traffic (the decrypted
|
|
# bot-token route). Must match the port in bot/.env's SITE_INTERNAL_URL and must
|
|
# never be exposed through a public reverse proxy. See issue #33.
|
|
INTERNAL_PORT=3001
|
|
# Logging — written to BOTH the console and a log file (default <server>/logs/app.log).
|
|
LOG_LEVEL=debug # console verbosity: error | warn | info | debug
|
|
FILE_LOG_LEVEL=debug # file verbosity
|
|
LOG_TO_FILE=true # set false for console-only
|
|
# LOG_DIR= # defaults to server/logs
|
|
# LOG_FILE=app.log
|
|
|
|
# Point at a local or Dockerized MariaDB
|
|
DB_HOST=127.0.0.1
|
|
DB_PORT=3306
|
|
DB_NAME=runic_gateway
|
|
DB_USER=runic
|
|
DB_PASSWORD=change-me-db-password
|
|
|
|
JWT_SECRET=dev-only-change-me
|
|
JWT_EXPIRES_IN=1d
|
|
COOKIE_SECURE=auto
|
|
COOKIE_NAME=rg_token
|
|
|
|
# Trusted-device MFA ("Trust this device"). The trust cookie's name, how long a
|
|
# device stays trusted (skips the TOTP step, never the password), the per-user cap
|
|
# (no silent pruning — an over-cap trust is refused), and how many single-use
|
|
# recovery codes are generated at 2FA enrollment.
|
|
TRUST_COOKIE_NAME=rg_trust
|
|
TRUSTED_DEVICE_TTL_DAYS=30
|
|
MAX_TRUSTED_DEVICES=10
|
|
RECOVERY_CODE_COUNT=10
|
|
|
|
# Encryption key for secrets stored at rest (OAuth client secrets in auth_providers).
|
|
# Any string — hashed to a 256-bit AES-GCM key. REQUIRED in production; in dev an
|
|
# insecure key is derived from JWT_SECRET if unset (with a warning).
|
|
SECRET_ENC_KEY=dev-only-change-me-too
|
|
|
|
# Public base URL of this app, used to build the OAuth redirect_uri
|
|
# (${APP_BASE_URL}/api/v1/auth/sso/:provider/callback). Set this in production so
|
|
# the callback URL matches what you register with Google/Discord. If unset, it is
|
|
# derived from the incoming request (fine for local dev).
|
|
APP_BASE_URL=http://localhost:5173
|
|
|
|
# Short-lived mobile access token lifetime + refresh token lifetime (Part 2).
|
|
MOBILE_ACCESS_TTL=15m
|
|
MOBILE_REFRESH_TTL_DAYS=30
|
|
|
|
# Reverse-proxy trust. Request path: client -> Pangolin -> newt agent "ptero"
|
|
# (separate VM) -> this app. ptero is the hop that connects to us, so pin
|
|
# TRUST_PROXY to ptero's LAN IP: Express then honours X-Forwarded-For ONLY on
|
|
# connections from ptero, and req.ip / req.secure reflect the real client (used
|
|
# by rate limiting, backoff, bot-ban, activity log).
|
|
# <ptero LAN IP> -> e.g. 10.0.0.42 (RECOMMENDED in prod; requires a static
|
|
# DHCP reservation for ptero in Omada — a lease change would
|
|
# silently break IP trust)
|
|
# an integer -> that many hops (fallback if you can't pin an IP)
|
|
# false -> no proxy (direct connections)
|
|
# NOTE: a blanket "true" is intentionally rejected (coerced to 1) — it would let
|
|
# clients spoof their IP via a forged X-Forwarded-For and dodge rate limits/bans.
|
|
TRUST_PROXY=1
|
|
|
|
# Set to 1 to log each request's raw peer address + X-Forwarded-For + resolved
|
|
# req.ip, so you can verify/refresh ptero's IP without redeploying. Noisy —
|
|
# leave off in normal operation.
|
|
DEBUG_TRUST_PROXY=0
|
|
|
|
# Optional TOTP two-factor (opt-in per user).
|
|
# TOTP_ISSUER defaults to BRAND_NAME; BRAND_* live in the root .env (see root .env.example)
|
|
TOTP_ISSUER=Runic Gateway
|
|
# How long the "password verified, awaiting code" step stays valid.
|
|
TOTP_CHALLENGE_TTL=5m
|
|
|
|
# Created on first boot if the users table is empty
|
|
ADMIN_USERNAME=admin
|
|
ADMIN_PASSWORD=change-me-admin-password
|
|
|
|
# Email is configured in Admin → Settings → Email (Gmail over OAuth2), not here.
|
|
# It reuses the Google auth provider's OAuth client and stores an encrypted
|
|
# refresh token in the DB. The contact recipient is the `contact_email` site
|
|
# setting; while email is unconfigured the contact form falls back to a mailto: link.
|
|
|
|
CLIENT_ORIGIN=http://localhost:5173
|
|
|
|
# Discord bot — internal API (server <-> bot/). BOT_INTERNAL_KEY MUST be
|
|
# byte-for-byte identical to the same variable in bot/.env.example — it is the
|
|
# only auth on both sides' /internal/* routes, so a mismatch silently breaks
|
|
# every server<->bot call with 401s. It also guards the server's
|
|
# /internal/bot-config route, which returns the DECRYPTED Discord token: with
|
|
# NODE_ENV=production the app REFUSES TO START if this is blank, a documented
|
|
# placeholder, or shorter than 16 chars (a warning only in dev). The Discord bot
|
|
# TOKEN itself is not an env var — it's entered in the admin panel and stored
|
|
# encrypted in the DB (see the bot_config table / SECRET_ENC_KEY above).
|
|
BOT_INTERNAL_URL=http://localhost:4100
|
|
BOT_INTERNAL_KEY=dev-only-change-me-bot-key
|
|
|
|
# News announcement pipeline (published news post -> every registered delivery
|
|
# leg). The dispatcher is an in-process poller; this tunes it. Links in the
|
|
# announcements use APP_BASE_URL (set above), so set that in production too.
|
|
#
|
|
# Which legs exist depends on what has registered one: Discord (#news) is core's,
|
|
# and an installed module may add its own. A module's leg brings its own settings
|
|
# with it -- module-uo's in-game town crier reads TOWNCRIER_DURATION_SEC, which is
|
|
# documented in that module rather than here, because core has no town crier.
|
|
ANNOUNCE_POLL_MS=15000
|
|
|
|
# Push notifications (M7) — opt-in fan-out to the Android app via a self-hosted
|
|
# ntfy UnifiedPush relay (docs/android/PLAN.md §11). The publisher POSTs
|
|
# content-free tickles to each device's endpoint, so no publish token is required.
|
|
# NTFY_BASE_URL Internal relay URL the publisher POSTs to; also part of the
|
|
# backend's SSRF allow-set — a device may only register an
|
|
# endpoint on an allowed origin.
|
|
# NTFY_PUBLIC_URL Client-facing relay URL surfaced to the app via
|
|
# /public/settings.push.ntfyUrl (the app registers its topic
|
|
# endpoint here). Defaults to the first NTFY_ALLOWED_ORIGINS
|
|
# entry; set when the public URL differs from NTFY_BASE_URL.
|
|
# NTFY_ALLOWED_ORIGINS Optional comma-separated allowed origins (the app's endpoint
|
|
# must sit on one). Also the default source for NTFY_PUBLIC_URL.
|
|
# NTFY_PUBLISH_TOKEN Optional bearer token for backend->ntfy publishes (off by default).
|
|
# Leave NTFY_BASE_URL unset in local dev to allow any public HTTPS endpoint
|
|
# (private/loopback hosts are always rejected). Without NTFY_PUBLIC_URL /
|
|
# NTFY_ALLOWED_ORIGINS the app shows push as unavailable for this instance.
|
|
# NTFY_BASE_URL=https://ntfy.example.com
|
|
# NTFY_PUBLIC_URL=https://ntfy.example.com
|
|
# NTFY_ALLOWED_ORIGINS=https://ntfy.example.com
|
|
# NTFY_PUBLISH_TOKEN=
|
|
|
|
# Modules (MODULE_SYSTEM.md §2.5) — where installable modules live, and where
|
|
# they may be installed from.
|
|
# MODULES_DIR Directory the loader scans at require time. Defaults to
|
|
# <repo>/modules; docker-compose.yml sets it to /app/modules,
|
|
# which is the bind mount that makes it meaningful.
|
|
# MODULE_SOURCE_HOSTS BOOTSTRAP ONLY. Comma-separated hostnames the admin panel
|
|
# may install a module from, seeded into the `module_source_hosts`
|
|
# setting the first time the site boots without one. From then
|
|
# on the SETTING is authoritative and is edited in
|
|
# Admin → Modules — changing this variable on an existing
|
|
# deployment does nothing, deliberately, so a redeploy cannot
|
|
# silently undo an operator's choice. Installs are https-only
|
|
# and an empty list forbids all of them.
|
|
# MODULES_DIR=/app/modules
|
|
# MODULE_SOURCE_HOSTS=gitea.whitlocktech.com
|