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
4 changes: 4 additions & 0 deletions .github/workflows/build.yml
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,10 @@ jobs:
- name: Build with Maven
run: mvn install

- if: ${{ runner.os == 'Linux' }}
name: Enforce Code Coverage Threshold
run: python3 scripts/check-coverage.py --per-file-limit 90

# Uploads the full dependency graph to GitHub to improve the quality of Dependabot alerts this repository can receive
- if: ${{ matrix.upload-dependency-graph && github.event_name != 'pull_request' }}
name: Update dependency graph
Expand Down
10 changes: 10 additions & 0 deletions .jules/sentinel.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,3 +32,13 @@
**Vulnerability:** In `DiskUtils.readSerializable`, `ValidatingObjectInputStream.accept()` used wide wildcards (`java.lang.*`, `java.util.*`, `me.desair.tus.server.*`) which permitted deserialization of any class within those packages, exposing potential gadget chains for insecure deserialization attacks.
**Learning:** Broad package wildcards in `ValidatingObjectInputStream` reduce the protection against insecure deserialization, allowing arbitrary classes within allowed packages to be instantiated during deserialization.
**Prevention:** Always construct explicit, concrete class allow-lists when using `ValidatingObjectInputStream.accept(...)` by supplying expected class literal references rather than wide package-level wildcards.

## 2026-11-08 - Prevent Path Traversal and MIME Sniffing in Download Extension
**Vulnerability:** In `DownloadGetRequestHandler.java`, `info.getFileName()` derived from user-supplied `Upload-Metadata` was embedded directly into the `Content-Disposition` header without stripping path traversal sequences (`../`, `..\`) or directory paths (`/`, `\`). Downstream clients saving files using the suggested filename could write files outside target directories. Additionally, `X-Content-Type-Options: nosniff` was missing when serving completed downloads, leaving browsers susceptible to MIME sniffing attacks.
**Learning:** File download endpoints that reflect user-supplied filenames in `Content-Disposition` headers can cause path traversal vulnerabilities on consuming clients. Serving user-uploaded content without explicit MIME-sniffing protection allows potential content sniffing / script execution.
**Prevention:** Sanitize filenames before constructing `Content-Disposition` by stripping directory paths (Unix `/` and Windows `\`), removing directory traversal sequences (`..`), and falling back to a safe identifier if the sanitized name is empty. Always include `X-Content-Type-Options: nosniff` when serving user-uploaded files.

## 2026-11-15 - Prevent Path Traversal in UploadInfo.getFileName()
**Vulnerability:** `UploadInfo.getFileName()` returned untrusted client-supplied metadata directly without sanitizing path traversal sequences (`../`, `..\`) or directory delimiters (`/`, `\`). Downstream consumers relying on `uploadInfo.getFileName()` to persist uploaded files were vulnerable to path traversal and arbitrary file overwrite outside the destination directory. Additionally, calling `getFileName()` on an `UploadInfo` with a null ID caused a `NullPointerException`.
**Learning:** Helper methods that extract filenames from untrusted client metadata must enforce path sanitization at the source, preventing downstream consumers from accidentally introducing path traversal vulnerabilities.
**Prevention:** Sanitize filenames at extraction in `UploadInfo.getFileName()` via `Utils.sanitizeFileName(...)`, stripping directory paths, traversal sequences, and null bytes while safely falling back to the upload ID or `"download"` if null.
16 changes: 9 additions & 7 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -129,13 +129,14 @@ To avoid duplicate test code and ensure all protocol integration tests run consi
### 17. The "2-Year Maintainability Rule" for Inline Documentation & Code Readability
- **The "2-Year Maintainability Rule"**: Every single fix, complicated or non-trivial code block, boundary condition, and `if`-test MUST include thorough inline comments explaining *why* that specific call, calculation, or branch condition was chosen. The code must be documented so clearly that after 2 years, any maintainer can immediately understand the reasoning, edge-case rationale, or protocol specification behind it without having to reverse-engineer the commit history.
- Write natural, explanatory comments describing the reasoning and intent directly. Do NOT prefix comments with literal meta-labels such as `The 2-Year Maintainability Rule:` or review audit section identifiers (e.g., `H5:`).
- **No Agent File References**: Never mention `AGENTS.md` or reference AGENTS.md rules in source code comments. Comments must describe the engineering intent and domain logic directly without referencing agent prompt files, meta-rules, or instruction documents.
- Keep comment line breaks balanced and clean within the 100-character column limit enforced by Google Java Style.
- Always write and preserve thorough inline comments across all main and test Java source files to explain non-obvious algorithms, multi-step operations, and complex logic.
- Ensure all function implementations remain short, clean, well-documented, and stick to the same level of abstraction. Use helper methods to break down complex logic into smaller, readable pieces.

### 18. Efficient Batch Test & Code Coverage Verification Strategy
To maximize developer velocity and minimize test execution overhead when increasing code coverage:
- **Batch Test Updates**: When addressing missing line/branch coverage reported by JaCoCo, batch multiple test additions across all relevant test classes (`S3StorageServiceTest`, `S3LockingServiceTest`, `S3UploadLockTest`, `S3ConcatenationServiceTest`, `UploadInfoSerializerTest`) at once rather than running test-by-test iterations.
- **Batch Test Updates**: When addressing missing line/branch coverage reported by JaCoCo, batch multiple test additions across all relevant test classes (`S3StorageServiceTest`, `S3LockingServiceTest`, `S3UploadLockTest`, `S3ConcatenationServiceTest`, `UploadInfoJsonSerializerTest`) at once rather than running test-by-test iterations.
- **Fast Unit Test Execution**: Verify all local unit tests rapidly using target wildcard patterns (e.g. `mvn test -Dtest="S3*" -q` or `mvn test -Dtest="*Test" -q`). Unit tests run in under 2 seconds without launching test containers.
- **Single Verification Gate**: Only run the python coverage script (`python3 scripts/check-coverage.py --per-file-limit 90`) after all batched unit test updates have been applied and locally validated.

Expand Down Expand Up @@ -183,12 +184,13 @@ To maintain a clear separation between fast, offline unit tests and containerize
- Do NOT use legacy `java.io.File.createTempFile(...)`. On POSIX systems, it creates files with overly permissive default umask permissions (often world-readable or group-readable, CWE-378 / SonarQube java:S5443).
- Always use `java.nio.file.Files.createTempFile(...)` (or `Utils.createTempSiblingPath(...)` / `Utils.createTempSibling(...)`), which creates temporary files with restricted owner-only permissions (`rw-------` / `0600`) by default.

### 23. Thread Safety: Prevent Volatile Class Variables & Use ReentrantReadWriteLock
### 23. Thread Safety: Prevent Volatile Class Variables & Use ReentrantReadWriteLock or Synchronized
- Do NOT use `volatile` class variables for mutable state, lazy compilation, or feature flags. `volatile` references on complex objects or mutable fields can trigger static analysis warnings (e.g. SonarQube java:S3077) and cannot guard multi-step compound actions, non-atomic transitions, or lazy initializations.
- Guard concurrent mutable state using a `ReadWriteLock` (`ReentrantReadWriteLock`).
- Consistently name the lock field `private final ReadWriteLock thisObjectLock = new ReentrantReadWriteLock();` in every class for pattern consistency across the codebase.
- Use `thisObjectLock.readLock()` for fast, concurrent reads, and `thisObjectLock.writeLock()` for state mutations, lazy pattern compilation, or feature capability degradation.
- Always acquire and release locks using `try ... finally` blocks (e.g. `thisObjectLock.readLock().lock(); try { return field; } finally { thisObjectLock.readLock().unlock(); }`).
- When a class requires both concurrent reads and exclusive writes, guard mutable state using a `ReadWriteLock` (`ReentrantReadWriteLock`):
- Consistently name the lock field `private final ReadWriteLock thisObjectLock = new ReentrantReadWriteLock();` in every class for pattern consistency across the codebase.
- Use `thisObjectLock.readLock()` for fast, concurrent reads, and `thisObjectLock.writeLock()` for state mutations, lazy pattern compilation, or feature capability degradation.
- Always acquire and release locks using `try ... finally` blocks (e.g. `thisObjectLock.readLock().lock(); try { return field; } finally { thisObjectLock.readLock().unlock(); }`).
- If a class only needs exclusive mutual exclusion (i.e. only `writeLock` semantics are used and no `readLock` is needed in the class), prefer the simpler `synchronized` keyword on the method or block rather than introducing a `ReadWriteLock`.

### 24. UploadLock AutoCloseable Lifecycle & Try-With-Resources
- `UploadLock` implements `java.lang.AutoCloseable`.
Expand All @@ -210,7 +212,7 @@ When a new draft revision of the IETF Resumable Uploads specification (`draft-ie
- Identify any changed header names, structured field syntax changes, response status codes, or problem details schemas.

### 2. Spec-Driven Compliance Test Maintenance
Compliance unit tests located in `src/test/java/me/desair/tus.server.rufh/` (`RufhProtocolCreationTest`, `RufhProtocolAppendTest`, `RufhProtocolHeadTest`, `RufhProtocolCancellationTest`, `HttpProblemDetailsTest`) contain verbatim quotes from the specification in their method Javadocs.
Compliance unit tests located in `src/test/java/me/desair/tus/server/rufh/` (`RufhProtocolCreationTest`, `RufhProtocolAppendTest`, `RufhProtocolHeadTest`, `RufhProtocolCancellationTest`, `HttpProblemDetailsTest`) contain verbatim quotes from the specification in their method Javadocs.
- **Workflow**:
1. Update the verbatim spec quotes in test method Javadocs to reflect the new draft revision text.
2. Update test assertions and expected header/status formats.
Expand Down
Loading
Loading