Skip to content

fix(server): baixa Paper via API fill v3 (v2 sunset -> jar corrompido) #6

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
oTalentz wants to merge 1 commit into
base: main
Choose a base branch
from
Open

fix(server): baixa Paper via API fill v3 (v2 sunset -> jar corrompido) #6

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
15 changes: 11 additions & 4 deletions Dockerfile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,10 +19,17 @@ RUN mkdir -p ${SERVER_DIR}/plugins/ViaVersion \
WORKDIR ${SERVER_DIR}

# ─── Baixar Paper ───
RUN apt-get update && apt-get install -y --no-install-recommends curl && \
curl -L -o paper-${PAPER_VERSION}.jar \
"https://api.papermc.io/v2/projects/paper/versions/${PAPER_VERSION}/builds/latest/downloads/paper-${PAPER_VERSION}.jar" && \
apt-get purge -y curl && apt-get autoremove -y && rm -rf /var/lib/apt/lists/*
# A API v2 (api.papermc.io/v2) foi DESCONTINUADA (sunset) e retorna 404.
# Usamos a API fill v3 para obter os metadados do build mais recente e
# extrair a URL real de download (hospedada em fill-data.papermc.io).
RUN apt-get update && apt-get install -y --no-install-recommends curl ca-certificates unzip && \
PAPER_META=$(curl -sL "https://fill.papermc.io/v3/projects/paper/versions/${PAPER_VERSION}/builds/latest") && \
PAPER_URL=$(echo "$PAPER_META" | grep -oE 'https://fill-data[^"]+\.jar' | head -1) && \
if [ -z "$PAPER_URL" ]; then echo "ERRO: nao foi possivel obter a URL do Paper ${PAPER_VERSION}" >&2; exit 1; fi && \
echo "Baixando Paper de: $PAPER_URL" && \
curl -L -o paper-${PAPER_VERSION}.jar "$PAPER_URL" && \
unzip -tqq paper-${PAPER_VERSION}.jar > /dev/null && \
Comment on lines +27 to +31

@coderabbitai coderabbitai Bot Jul 21, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔒 Security & Privacy | 🟠 Major | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf '== Files ==\n'
git ls-files Dockerfile scripts/setup.bat

printf '\n== Dockerfile excerpt ==\n'
nl -ba Dockerfile | sed -n '1,80p'

printf '\n== scripts/setup.bat excerpt ==\n'
nl -ba scripts/setup.bat | sed -n '1,120p'

printf '\n== Search for checksum/hash handling ==\n'
rg -n "sha256|checksum|Get-FileHash|sha512|hash" -S . || true

Repository: oTalentz/plugin-minecraft-2026

Length of output: 275

🌐 Web query:

PaperMC fill v3 downloads server:default checksums sha256 documentation

💡 Result:

PaperMC has transitioned to a new download service named Fill (formerly Bibliothek), which uses the v3 API [1]. This service is hosted at fill.papermc.io [2][1]. Unlike previous versions, you should no longer manually construct download URLs; instead, you retrieve them directly from the API responses [1][3]. Key Technical Details for Fill v3: Base URL: All requests should be made to https://fill.papermc.io [2][1]. Downloads and Checksums: In the v3 API, download information—including the SHA256 checksum and the direct download URL—is embedded directly within the build object [4][3]. The primary download key for the server JAR is server:default [2][4][1]. API Response Structure: A typical build response includes a downloads object containing the server:default entry. This entry provides the following fields [4]: name: The filename (e.g., paper-1.21.8-56.jar) [4] url: The absolute URL to the binary, hosted at fill-data.papermc.io [4][1] checksums: An object containing the sha256 hash string [2][4] size: The size of the file in bytes [4] Implementation Notes: User-Agent: It is required to provide a descriptive User-Agent header when making requests to the Fill v3 API [5][3]. GraphQL: An experimental GraphQL API is also available for more complex queries at https://fill.papermc.io/graphql [2][1]. Deprecated API: The older v1/v2 API at api.papermc.io has been sunset and should no longer be used [1][3]. For detailed interactive documentation and schema exploration, you can access the Swagger UI documentation typically provided by the service [1]. Always ensure your scripts resolve the download URL dynamically from the JSON response rather than using hardcoded paths [1][3].

Citations:

🏁 Script executed:

#!/bin/bash
set -euo pipefail

python3 - <<'PY'
import urllib.request, json
url = 'https://docs.papermc.io/misc/downloads-service/'
try:
    with urllib.request.urlopen(url, timeout=20) as r:
        data = r.read().decode('utf-8', 'replace')
    print('Fetched docs length:', len(data))
    for needle in ['checksums', 'sha256', 'server:default', 'downloads']:
        idx = data.lower().find(needle.lower())
        print(f'Needle {needle!r}:', idx)
        if idx != -1:
            start = max(0, idx-300)
            end = min(len(data), idx+900)
            print(data[start:end])
            print('---')
except Exception as e:
    print('ERROR', type(e).__name__, e)
PY

Repository: oTalentz/plugin-minecraft-2026

Length of output: 317

🏁 Script executed:

#!/bin/bash
set -euo pipefail

# Show the exact context around the two download paths and whether any digest validation exists elsewhere.
sed -n '1,120p' Dockerfile | nl -ba
printf '\n---\n'
sed -n '1,120p' scripts/setup.bat | nl -ba
printf '\n---\n'
rg -n "Invoke-FileHash|sha256sum|checksums\.sha256|server:default|fill-data" Dockerfile scripts setup* . -S || true

Repository: oTalentz/plugin-minecraft-2026

Length of output: 208

🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf '== Dockerfile ==\n'
sed -n '1,80p' Dockerfile | cat -n

printf '\n== scripts/setup.bat ==\n'
sed -n '1,120p' scripts/setup.bat | cat -n

printf '\n== Existing digest/hash handling ==\n'
rg -n "sha256|checksum|Get-FileHash|sha512|hash" -S Dockerfile scripts . || true

Repository: oTalentz/plugin-minecraft-2026

Length of output: 7636

Verify the Paper JAR digest before using it.

  • Dockerfile#L27-L31: unzip -tqq only checks archive structure; compare the downloaded JAR against downloads."server:default".checksums.sha256 before accepting it.
  • scripts/setup.bat#L35-L36: add the same SHA-256 check before the downloaded JAR is used.
📍 Affects 2 files
  • Dockerfile#L27-L31 (this comment)
  • scripts/setup.bat#L35-L36
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@Dockerfile` around lines 27 - 31, Verify the downloaded Paper JAR’s SHA-256
digest against downloads."server:default".checksums.sha256 before it is accepted
or used: update the Dockerfile download flow near unzip -tqq and add the
equivalent check in scripts/setup.bat near the JAR download. Preserve the
existing failure behavior and reject the artifact when the digest does not
match.

Source: MCP tools

apt-get purge -y curl unzip && apt-get autoremove -y && rm -rf /var/lib/apt/lists/*

# ─── Baixar Plugins ───
RUN apt-get update && apt-get install -y --no-install-recommends curl && \
Expand Down
3 changes: 2 additions & 1 deletion scripts/setup.bat
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,8 @@ if exist "%PAPER_JAR%" (
echo [WARN] %PAPER_JAR% ja existe. Pulando download.
) else (
echo [INFO] Baixando Paper %PAPER_VERSION%...
powershell -Command "Invoke-WebRequest -Uri 'https://api.papermc.io/v2/projects/paper/versions/%PAPER_VERSION%/builds/latest/downloads/paper-%PAPER_VERSION%.jar' -OutFile '%PAPER_JAR%'"
REM A API v2 foi DESCONTINUADA (sunset). Usamos a API fill v3 para obter a URL real.
powershell -Command "$meta = Invoke-RestMethod -Uri 'https://fill.papermc.io/v3/projects/paper/versions/%PAPER_VERSION%/builds/latest'; Invoke-WebRequest -Uri $meta.downloads.'server:default'.url -OutFile '%PAPER_JAR%'"
Comment on lines +35 to +36

@coderabbitai coderabbitai Bot Jul 21, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔒 Security & Privacy | 🟠 Major | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf '--- scripts/setup.bat ---\n'
nl -ba scripts/setup.bat | sed -n '1,120p'

printf '\n--- search for sha256 / fill / papermc in repo ---\n'
rg -n "sha256|fill\.papermc\.io|papermc\.io|Invoke-RestMethod|Invoke-WebRequest" -S .

Repository: oTalentz/plugin-minecraft-2026

Length of output: 259

🌐 Web query:

PaperMC downloads service fill v3 sha256 metadata server:default url docs origin checksum

💡 Result:

PaperMC's download service, now referred to as Fill v3, serves as the successor to the previous Bibliothek (v2) API [1][2]. All automated tools, scripts, and server hosts must migrate to the new fill.papermc.io domain, as the old api.papermc.io endpoint has been sunset [1][3][2]. Key changes and technical details for Fill v3 include: 1. API Endpoint and Domain: The primary domain is now fill.papermc.io [1][2]. The REST API and an experimental GraphQL endpoint (https://fill.papermc.io/graphql) are hosted here [4][1]. 2. Download URLs: Download links are no longer manually constructed. They are now embedded directly in the API response under the url field and point to the fill-data.papermc.io domain [1][3][2]. 3. Metadata and Keys: - The key for the standard server jar has been updated from application (used in v2) to server:default [3][2]. - Other keys include server:mojang for Mojang-mapped jars [2]. - API responses now include comprehensive metadata, including SHA256 checksums and file sizes, located within the checksums object [4][5][3]. 4. Required Headers: All requests to the Fill v3 API must include a non-generic User-Agent header (e.g., identifying the project, bot, or contact info) to avoid rate-limiting or rejection [4][6][3]. Example GraphQL query for fetching the latest stable build download URL: query LatestStableBuildDownloadURL { project(key: "paper") { key versions(first: 1, orderBy: {direction: DESC}) { edges { node { key builds(filterBy: { channel: STABLE }, first: 1, orderBy: { direction: DESC }) { edges { node { number download(key: "server:default") { name url checksums { sha256 } size } } } } } } } } } Official documentation for the service is maintained at the PaperMC Downloads Service documentation page [4].

Citations:

🌐 Web query:

site:docs.papermc.io downloads service fill v3 sha256 server:default url

💡 Result:

The term "server:default" appears as a specific key used within the PaperMC Downloads Service API [1]. It is utilized when querying for the download information of a project build (such as Paper) to specify which artifact download should be returned [1]. In the context of the PaperMC Downloads Service GraphQL API, when you request the download object for a build, you provide key: "server:default" to retrieve the primary server JAR file [1]. The response for this query includes the following fields [1]: - name: The filename of the download. - url: The direct URL to the artifact (e.g., hosted on fill-data.papermc.io) [1]. - checksums: A nested object containing the sha256 hash of the file [1]. - size: The size of the file in bytes [1]. The "v3" mentioned in your query refers to the versioning of the data API endpoints (e.g., https://fill-data.papermc.io/v3/...) used by PaperMC to serve these artifacts [1]. The "fill" in the URL path is associated with the storage or delivery service for these downloads [1]. If you are interacting with this API programmatically, you would use these fields to verify the integrity of the downloaded file using the provided SHA-256 checksum [1].

Citations:

🏁 Script executed:

#!/bin/bash
set -euo pipefail

nl -ba scripts/setup.bat | sed -n '1,120p'

printf '\n--- matches ---\n'
rg -n "sha256|fill\.papermc\.io|papermc\.io|Invoke-RestMethod|Invoke-WebRequest" -S .

Repository: oTalentz/plugin-minecraft-2026

Length of output: 208

Compare the downloaded JAR to Fill’s checksums.sha256. The metadata already supplies the direct URL, but the script still accepts the file without any integrity check. A hash match before the success message would catch corrupted or substituted artifacts.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@scripts/setup.bat` around lines 35 - 36, Update the PowerShell download
command in the setup script to retrieve and validate Paper’s checksums.sha256
against the downloaded file before reporting success. Use the metadata/download
URL flow around PAPER_VERSION and PAPER_JAR, ensure a hash mismatch fails the
setup, and only continue after a successful integrity check.

Source: MCP tools

echo [OK] Paper baixado.
)

Expand Down