Files
Snipzil 131fb8b025 docs(contributing): add security guidelines for GitHub webhooks
Include instructions on verifying route signatures for signed push
webhooks and precautions against exposing webhook secrets in logs,
commits, or pull requests.
2026-10-20 21:42:02 -04:00

4.6 KiB

Contributing to Burrow

Thanks for helping make Burrow safer, kinder, and more reliable. Keep changes small, explain the player-facing effect, and open a pull request against the repository's default branch.

Local setup

Use Node.js 22.5 or later, Git, and an existing checkout containing the tracked client and cached game assets. Install the reviewed runtime dependency with:

npm ci

Run the server with:

npm start

The local web server defaults to http://127.0.0.1:8080 and the game server to port 9339. Do not commit data/, cache/, .env files, tokens, recovery-mail credentials, Discord bot tokens, or production exports.

Before opening a pull request

Run the smoke suite and repository invariants from the repository root:

npm test
node .github/scripts/invariants.js

Add focused coverage under test/ when changing a game protocol, permissions, account state, moderation, or web route. Explain any test that cannot run locally and include the exact failure output.

Use Conventional Commit messages; the pull-request workflow checks them. Keep the change limited to its purpose and describe security implications, especially for authentication, staff permissions, moderation, player data, network input, or media.

Security requirements

Burrow handles account credentials, 2FA, game sessions, player reports, and moderation records. Treat every browser, game, and Discord input as untrusted.

  • Never log, display, or commit passwords, session tokens, recovery links, IP addresses, device identifiers, private keys, or bot tokens.
  • Do not add web hosts, execute programs from server code, evaluate generated text, or add dependencies without updating and explaining the invariant checks.
  • [email protected] is the only approved runtime dependency. Keep it exactly pinned and update package-lock.json in the same pull request when its reviewed version changes.
  • Preserve permission checks and staff-rank protections. New moderation actions must use the existing role model and leave an audit record.

The CI security workflow parses all server JavaScript, checks allowed external hosts, scans commits for secrets, and reviews the Flash files that clients load.

Discord bot changes

The optional Discord staff bot is enabled only with AJ_DISCORD_BOT_TOKEN and AJ_DISCORD_GUILD_ID. It trusts a Discord user only after the user has linked that identity to an active Burrow staff account with 2FA. Do not create an alternate Discord-only permission system.

All visible bot messages, including errors, status cards, reports, audit logs, and interaction updates, must use Discord Components V2: set MessageFlags.IsComponentsV2 and use containers/text displays rather than content or embeds. Keep player-supplied text safe from mentions and avoid relaying chat, addresses, device data, or tokens to Discord.

GitHub update cards are produced only from signed push webhooks. Keep that route signature-verified before parsing or posting a payload, limit request size, and do not expose webhook secrets in commits, logs, cards, or pull requests.

Server and panel changes

The server code lives in lib/; browser pages live in public/; protocol behavior is primarily in lib/world.js and the related feature modules. Reuse the panel's shared moderation action path instead of copying bans, warnings, silences, or rank checks into a new surface.

Document new environment variables in README.md. Make optional integrations fail closed or remain disabled when configuration is absent; they must never stop gameplay, moderation records, or account storage when an external service is unavailable.

Client and asset changes

Changes under swf-src/ require rebuilding the tracked client with Java and JPEXS/FFDec:

tools/build-client.sh

On Windows, run the script through Git Bash or an equivalent POSIX shell. Commit both the source change and the resulting swf/ajclient.swf when the client is changed. Do not edit files under tools/decompiled/ unless the build tool explicitly consumes that source; they are reference output.

Badge artwork is generated by tools/make-badges.py; follow the script's usage notes and commit all generated badge assets together.

Pull-request checklist

  • The change has a clear player, staff, or maintenance outcome.
  • Tests and invariants pass, or the exception is explained.
  • No secret, personal data, cache, database, or generated local output is included.
  • New Discord output uses Components V2 and respects the existing permission/audit model.
  • Client source and rebuilt SWF are both included when applicable.