Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 17 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,22 @@ With a hash file, Packmule also looks for `<same folder>/<sha1>.zip`. If that ad

Leaf Juice serves its recipes at both kinds of address, but Packmule works with any host.

### Packs only your players can download

Leaf Juice can serve a pack only to players joining the server: it checks the game's own request headers against the whitelist and the server log, and refuses everyone else. Packmule's startup check isn't a player, so a pack like that needs a `check` block:

```yaml
packs:
private:
url: https://join.example.com/zz/TOKEN/0123456789abcdef0123456789abcdef01234567.zip
check:
public-prefix: https://join.example.com/zz/
local-prefix: http://127.0.0.1:8766/
token-file: ~/Library/Application Support/LeafJuice/pack-check/my-server.token
```

Packmule then checks the pack at the local address, sending the token from the file in an `X-Pack-Check-Token` header. Players still get `url`. Packmule refuses the config if `local-prefix` isn't on this machine (127.0.0.1, ::1 or localhost) or `public-prefix` isn't the start of `url`. It refuses the check if the token file is a link, belongs to another user, can be read by anyone else (it must be mode 600), or doesn't hold 64 hex characters. A token request never follows a redirect, and the token is never logged. `/packmule pack set` keeps the block when the new address is still under `public-prefix`. Your web server should strip `X-Pack-Check-Token` from outside requests.

## Install

1. Put `Packmule-<version>.jar` in `plugins/` and start the server once.
Expand Down Expand Up @@ -102,7 +118,7 @@ The jar is `build/libs/Packmule-<version>.jar`. A `v*` tag builds it and attache

## Tests

`./gradlew test` runs the unit tests: config parsing, the link checker against a local web server, and the pack diff.
`./gradlew test` runs the unit tests: config parsing, the link checker against a local web server, the check for gated packs against a made-up gate, and the pack diff.

`test/` holds the bot tests. They start throwaway Paper servers on 127.0.0.1:25613 in a temp folder you choose, and serve made-up packs on 127.0.0.1:25614. Bots connect as 26.1 clients: directly on 26.1.2, and through ViaVersion and ViaBackwards on 26.2 and 26.3. They answer pack requests the way the client's pack manager does, and download and hash each pack. `test/waystation.mjs` walks a bot through a Waystation gate and back.

Expand Down
2 changes: 1 addition & 1 deletion build.gradle.kts
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ plugins {
}

group = "com.extantape"
version = "0.3.0"
version = "0.4.0"

java {
toolchain.languageVersion.set(JavaLanguageVersion.of(25))
Expand Down
5 changes: 5 additions & 0 deletions docs/decisions.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,3 +30,8 @@ Owner decisions that shape Butler, with the date each was made. Change these onl
- **Name (2026-11-08, owner):** ResourcePackButler is renamed Packmule, one word in every place: repo, plugin name, jar, package and prose. Released as 0.2.0. Existing servers get their `plugins/ResourcePackButler/` folder copied on first start (never overwritten), and the old commands and permissions keep working for one release with a log warning. Pack IDs keep the old `resourcepackbutler:pack:` namespace for good, because clients see them.
- **pack set for Leaf Juice (2026-11-14, D189):** each pack build is published at a new unguessable path on the join host, and Leaf Juice hands Packmule the new link through `/packmule pack set <pack> <url> --json <id>`, as the Leaf Juice App session proposed and Helm assigned (K644). It takes https only, with the SHA-1 as the file name. Packmule downloads the file and checks the SHA-1 before writing `config.yml` (comments kept) and reloading, and a failure keeps the old address. Released as 0.2.1, so the old ResourcePackButler names stay for this 0.2.x release as promised.
- **Old names (2026-11-14, owner):** the ResourcePackButler commands, permissions, folder copy and pack ID namespace are gone; pack IDs are now packmule:pack:<name>, so clients download each pack once more.

## 2026-11-15

- **Packs only players can download (D219, D220):** a private texture pack goes only to players joining the server, through Leaf Juice's joining-only gate. Packmule's startup check isn't a player, so a pack can carry a `check` block: Packmule checks it at a loopback address with a token from a mode-600 file, and players keep the public address. Agreed with the Head of Software (Leaf Juice side: the token file lives in Leaf Juice's Application Support folder, and Leaf Juice refuses the token on any proxied request) and the Head of Infrastructure (Caddy strips the header). Packmule refuses non-loopback local addresses, linked or shared token files and redirects on token requests. Released as 0.4.0.

14 changes: 14 additions & 0 deletions docs/releases/v0.4.0.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
Packmule can check packs that only your players can download.

## Added

- **A `check` block per pack** for packs behind a gate that admits only joining players, such as Leaf Juice's "Only players joining this server". Packmule checks the pack at a loopback address with a token read from a mode-600 file, and players still get the public address. See "Packs only your players can download" in the README.
- The config is refused if the local address isn't on this machine or the public prefix isn't the start of the pack's address. The check fails if the token file is a link, another user's, readable by others or malformed. Token requests never follow redirects, and the token is never logged.

## Upgrading

Replace the jar and restart. Configs without a `check` block work as before.

## Tested

Unit tests against a made-up gate on 127.0.0.1 (51 tests). Not yet run against Leaf Juice's own gate; that waits for its side (D220).
14 changes: 14 additions & 0 deletions docs/test-audit.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,3 +27,17 @@ Each README promise and the test that holds it. "Bots" is `test/suite.mjs` on th
**Skipped, with reasons:**
- "No background polling": it's an absence of code (there's no scheduled check); a test watching for traffic over time would prove little more than reading `Packmule.java`, done at this audit.
- How the prompt and kick messages read on screen, and how a real loading screen feels: real client only, listed under "What hasn't been tested".

## 2026-11-15: gated packs (0.4.0)

| Promise | Test |
| --- | --- |
| A gated pack is checked at the local address with the token, and players keep the public address | unit `checksAtTheLocalAddressWithTheTokenAndPlayersKeepThePublicOne` |
| Without a check block the gate refuses Packmule's check | unit `withoutTheCheckBlockTheGateRefusesTheCheck` |
| **The token never leaves this machine:** non-loopback, user-part, wrong-prefix and incomplete check blocks are config errors | unit `refusesACheckBlockThatCouldSendTheTokenAway`, `loopbackMeansThisMachineOnly` |
| **The token never follows a redirect** or goes to an address outside the public prefix | unit `theTokenNeverFollowsARedirect`, `addressesOutsideThePublicPrefixGoWithoutTheToken` |
| **Fail closed on the token file:** shared (not 600), linked, missing or malformed files fail the check, and the token isn't in the reason | unit `aTokenFileOthersCanReadIsRefusedAndNothingIsSent`, `aLinkedTokenFileIsRefused`, `aMissingOrMalformedTokenFileIsRefused`, `aWrongTokenIsDead` |
| The check block is read | unit `readsAGatedPacksCheckBlock` |

**Gaps:** `/packmule pack set` keeping the block is a three-line lookup in `Packmule.gatedCheck`, covered by reading it; a bot test needs Leaf Juice's half (D220), so it runs with the refusal tests against the real gate.
**Skipped:** a file owned by another user, since a test can't create one without root; the owner comparison is one line next to the tested mode check.
9 changes: 8 additions & 1 deletion src/main/java/com/extantape/packmule/Packmule.java
Original file line number Diff line number Diff line change
Expand Up @@ -132,11 +132,18 @@ public List<String> reload() {
* /packmule reload. Any failure leaves config.yml and the pack as they were. {@code done} gets the outcome on the
* main thread: null when it worked, or the refusal.
*/
/** A gated pack keeps its check block when Leaf Juice hands it a new address, as long as the address stays under it. */
private PackmuleConfig.Check gatedCheck(com.extantape.packmule.command.PackSet.Plan plan) {
PackSource old = config.packs().get(plan.pack());
if (old == null || old.check() == null || !plan.url().startsWith(old.check().publicPrefix())) return null;
return old.check();
}

public boolean setPack(com.extantape.packmule.command.PackSet.Plan plan, java.util.function.Consumer<com.extantape.packmule.command.PackSet.Refused> done) {
if (setting) return false;
setting = true;
LinkChecker checker = new LinkChecker(Duration.ofSeconds(config.checkTimeoutSeconds()));
CompletableFuture.supplyAsync(() -> checker.check(new PackSource(plan.pack(), plan.url(), plan.sha1(), null), null), checks)
CompletableFuture.supplyAsync(() -> checker.check(new PackSource(plan.pack(), plan.url(), plan.sha1(), null, gatedCheck(plan)), null), checks)
.whenComplete((outcome, error) -> {
if (!isEnabled()) return;
Bukkit.getScheduler().runTask(this, () -> {
Expand Down
57 changes: 57 additions & 0 deletions src/main/java/com/extantape/packmule/check/CheckToken.java
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
package com.extantape.packmule.check;

import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.LinkOption;
import java.nio.file.Path;
import java.nio.file.attribute.PosixFileAttributes;
import java.nio.file.attribute.PosixFilePermission;
import java.util.EnumSet;
import java.util.Set;
import java.util.regex.Pattern;

/**
* Reads the pack-check token for a gated pack (D219). The file must be a plain file, not a link, owned by the user
* the server runs as, readable by nobody else, and hold exactly 64 hex characters. Anything else is refused, so a
* gated pack fails its check instead of going out with a token someone else could have read or swapped.
* The token itself never appears in a message.
*/
final class CheckToken {
private static final Pattern TOKEN = Pattern.compile("[0-9a-f]{64}");
private static final Set<PosixFilePermission> OWNER_ONLY = EnumSet.of(PosixFilePermission.OWNER_READ, PosixFilePermission.OWNER_WRITE);

private CheckToken() {
}

static String read(String file) throws LinkChecker.CheckFailed {
String shown = "check token file " + file;
Path path;
try {
path = Path.of(file.startsWith("~/") ? System.getProperty("user.home") + file.substring(1) : file);
} catch (RuntimeException e) {
throw new LinkChecker.CheckFailed(shown + " isn't a valid path");
}
try {
PosixFileAttributes a = Files.readAttributes(path, PosixFileAttributes.class, LinkOption.NOFOLLOW_LINKS);
if (!a.isRegularFile()) throw new LinkChecker.CheckFailed(shown + " isn't a plain file");
if (!a.owner().getName().equals(System.getProperty("user.name"))) throw new LinkChecker.CheckFailed(shown + " belongs to another user");
if (!OWNER_ONLY.containsAll(a.permissions())) throw new LinkChecker.CheckFailed(shown + " can be read by others; it must be mode 600");
if (a.size() > 256) throw new LinkChecker.CheckFailed(shown + " doesn't hold a token");
} catch (UnsupportedOperationException e) {
throw new LinkChecker.CheckFailed(shown + " can't be checked on this file system");
} catch (java.nio.file.NoSuchFileException e) {
throw new LinkChecker.CheckFailed(shown + " doesn't exist");
} catch (IOException e) {
throw new LinkChecker.CheckFailed(shown + " can't be read");
}
String text;
try {
text = Files.readString(path, StandardCharsets.US_ASCII).strip();
} catch (IOException | RuntimeException e) {
throw new LinkChecker.CheckFailed(shown + " can't be read");
}
if (!TOKEN.matcher(text).matches()) throw new LinkChecker.CheckFailed(shown + " doesn't hold a token");
return text;
}
}
31 changes: 24 additions & 7 deletions src/main/java/com/extantape/packmule/check/LinkChecker.java
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
package com.extantape.packmule.check;

import com.extantape.packmule.config.PackmuleConfig;
import com.extantape.packmule.config.PackmuleConfig.Check;
import com.extantape.packmule.config.PackmuleConfig.PackSource;

import java.io.IOException;
Expand Down Expand Up @@ -64,7 +65,7 @@ public Outcome check(PackSource source, String lastGood) {
} else {
String read;
try {
read = readHashFile(source.sha1Url());
read = readHashFile(source.sha1Url(), source.check());
} catch (CheckFailed e) {
read = null;
notes.add("Couldn't read its hash file " + source.sha1Url() + ": " + e.getMessage() + ".");
Expand All @@ -88,7 +89,7 @@ public Outcome check(PackSource source, String lastGood) {
for (int i = 0; i < candidates.size(); i++) {
String url = candidates.get(i);
try {
String got = downloadSha1(url);
String got = downloadSha1(url, source.check());
if (got.equals(sha1)) {
boolean build = source.movingAddress() ? i == 0 : PackmuleConfig.sha1FromAddress(url) != null;
if (source.movingAddress() && i > 0) {
Expand All @@ -111,38 +112,54 @@ private static Outcome dead(PackSource source, String reason, List<String> notes

/** The first 40-hex word of the hash file, lowercased. sha1sum's "hash filename" form works too. */
String readHashFile(String url) throws CheckFailed {
byte[] body = fetch(url, MAX_HASH_FILE, null);
return readHashFile(url, null);
}

String readHashFile(String url, Check check) throws CheckFailed {
byte[] body = fetch(url, MAX_HASH_FILE, null, check);
String text = new String(body, StandardCharsets.UTF_8).trim();
String first = text.isEmpty() ? "" : text.split("\\s+", 2)[0].toLowerCase(Locale.ROOT);
if (!PackmuleConfig.isSha1(first)) throw new CheckFailed("it doesn't hold a SHA-1");
return first;
}

String downloadSha1(String url) throws CheckFailed {
return downloadSha1(url, null);
}

String downloadSha1(String url, Check check) throws CheckFailed {
MessageDigest digest;
try {
digest = MessageDigest.getInstance("SHA-1");
} catch (NoSuchAlgorithmException e) {
throw new IllegalStateException(e);
}
fetch(url, MAX_BYTES, digest);
fetch(url, MAX_BYTES, digest, check);
return HexFormat.of().formatHex(digest.digest());
}

/** Downloads into the digest, or returns the body when there's no digest. */
private byte[] fetch(String url, long limit, MessageDigest digest) throws CheckFailed {
private byte[] fetch(String url, long limit, MessageDigest digest, Check check) throws CheckFailed {
String problem = PackmuleConfig.addressProblem(url);
if (problem != null) throw new CheckFailed("bad address, because " + problem);
// A gated pack is checked on this machine, with the token. Anything not under the public prefix goes as usual.
String token = null;
if (check != null && url.startsWith(check.publicPrefix())) {
url = check.localPrefix() + url.substring(check.publicPrefix().length());
token = CheckToken.read(check.tokenFile());
}
HttpURLConnection connection = null;
long started = System.nanoTime();
try {
connection = (HttpURLConnection) URI.create(url).toURL().openConnection();
connection.setConnectTimeout((int) timeout.toMillis());
connection.setReadTimeout((int) timeout.toMillis());
connection.setInstanceFollowRedirects(true);
// The token must never follow a redirect somewhere else.
connection.setInstanceFollowRedirects(token == null);
connection.setRequestProperty("User-Agent", "Packmule");
if (token != null) connection.setRequestProperty(Check.HEADER, token);
int code = connection.getResponseCode();
if (code != 200) throw new CheckFailed("HTTP " + code);
if (code != 200) throw new CheckFailed("HTTP " + code + (token != null ? " from the local check address" : ""));
var buffer = new java.io.ByteArrayOutputStream();
long total = 0;
byte[] chunk = new byte[64 * 1024];
Expand Down
Loading
Loading