This is an automated email from the ASF dual-hosted git repository. cziegeler pushed a commit to branch maia/workflow-1784204416925 in repository https://gitbox.apache.org/repos/asf/sling-org-apache-sling-security.git
commit 4fc74f637155716cd9ea12ce90501c72aa3139c2 Author: Carsten Ziegeler <[email protected]> AuthorDate: Thu Jul 16 14:20:16 2026 +0200 docs: improve AGENTS.md and README.md with filter details and commands Co-authored-by: Maia <maia@noreply> --- AGENTS.md | 11 ++++++++--- README.md | 8 ++++++-- 2 files changed, 14 insertions(+), 5 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 0c764a1..7d43136 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,13 +1,16 @@ # Project Overview -Apache Sling Security is an OSGi bundle for Apache Sling that provides two servlet filters: `ReferrerFilter` (a `Preprocessor` that blocks requests with missing or untrusted `Referer` headers to prevent CSRF) and `ContentDispositionFilter` (a Sling request/forward filter that forces `Content-Disposition: attachment` on responses for configured paths/content types). Components use OSGi R6/R7 declarative services annotations (`org.osgi.service.component.annotations`) with metatype configur [...] +Apache Sling Security is an OSGi bundle for Apache Sling that provides two servlet filters: `ReferrerFilter` (an OSGi HTTP Whiteboard `Preprocessor` that blocks requests with missing or untrusted `Referer`/`Origin` headers to prevent CSRF) and `ContentDispositionFilter` (a Sling request/forward filter that forces `Content-Disposition: attachment` on responses for configured paths/content types). Components use OSGi R6/R7 declarative services annotations (`org.osgi.service.component.annot [...] + +This bundle can run outside Apache Sling; in that setup only `ReferrerFilter` is applicable because `ContentDispositionFilter` depends on Sling API/resource model types. # Core Commands - **Build:** `mvn clean install` - **Build (skip tests):** `mvn clean install -DskipTests` - **Run full test suite:** `mvn test` -- **Run a single test class:** `mvn test -Dtest=ReferrerFilterTest` +- **Run ReferrerFilter tests:** `mvn test -Dtest=ReferrerFilterTest` +- **Run ContentDispositionFilter tests:** `mvn test -Dtest=ContentDispositionFilterTest` - **Run a single test method:** `mvn test -Dtest=ReferrerFilterTest#testMethodName` - **Lint / format check (Spotless via parent POM):** `mvn spotless:check` - **Apply formatting:** `mvn spotless:apply` @@ -40,6 +43,7 @@ All production code lives under `org.apache.sling.security.impl`. There are no p # Development Patterns & Constraints - **Java version:** 11 (source and target) +- **Parent POM:** `org.apache.sling:sling-bundle-parent:66` controls shared plugin/version management. - **OSGi components:** Use `org.osgi.service.component.annotations` (`@Component`, `@Reference`, `@Activate`). Do NOT use Felix SCR annotations. - **Metatype config:** Define configuration interfaces with `@ObjectClassDefinition` / `@AttributeDefinition` in the same file as or alongside the component. - **Indentation:** 4 spaces (no tabs). Follow existing code style. @@ -71,8 +75,10 @@ All production code lives under `org.apache.sling.security.impl`. There are no p # Gotchas - `ReferrerFilter` is registered as an OSGi `Preprocessor` (HTTP Whiteboard), not a standard Sling filter — it runs before Sling servlet resolution. +- `ReferrerFilter` validates `referer` and falls back to `origin` when `referer` is missing. - The `bnd.bnd` sets `Require-Capability` for `osgi.http` version 1.x; updating the HTTP Whiteboard spec version requires updating this too. - `org.apache.sling.*` imports are marked `resolution:=optional` so the bundle can load even when Sling API is absent — keep this in mind when adding Sling API usage. +- `ContentDispositionFilter` only adds the header for resources containing `jcr:data` directly or under `jcr:content/jcr:data`. - OSGi metatype XML descriptors are generated at compile time by annotation processing into `target/classes/OSGI-INF/`. Never edit them manually. - The parent POM (`sling-bundle-parent`) controls Spotless, RAT, baseline, and other plugin versions. Do not override plugin versions locally unless necessary. - `junit-addons:1.4` is a transitive test dependency with old Xerces — it is pulled in by JMock; avoid adding more dependencies on it. @@ -82,4 +88,3 @@ All production code lives under `org.apache.sling.security.impl`. There are no p <!-- sling-security-default:start --> The threat model for this project is https://github.com/apache/sling/blob/master/docs/threat-model.md . <!-- sling-security-default:end --> - diff --git a/README.md b/README.md index de8e32d..a8a409f 100644 --- a/README.md +++ b/README.md @@ -25,6 +25,9 @@ The project inherits build plugins and checks from Sling parent POM `66`. - Build: `mvn clean install` - Build without tests: `mvn clean install -DskipTests` - Run tests: `mvn test` +- Run ReferrerFilter tests: `mvn test -Dtest=ReferrerFilterTest` +- Run ContentDispositionFilter tests: `mvn test -Dtest=ContentDispositionFilterTest` +- Run a single test method: `mvn test -Dtest=ReferrerFilterTest#testMethodName` - Run Spotless check: `mvn spotless:check` - Apply Spotless formatting: `mvn spotless:apply` - Run RAT license checks: `mvn rat:check` @@ -34,6 +37,7 @@ The project inherits build plugins and checks from Sling parent POM `66`. The Referrer Filter is registered as an OSGi HTTP Whiteboard `Preprocessor` and checks browser-originated modification requests. It validates the `referer` header and falls back to `origin` when `referer` is not present. +The filter is applied to configured modification methods and supports path and user-agent based exclusions. Configuration PID: `org.apache.sling.security.impl.ReferrerFilter` @@ -76,9 +80,9 @@ It is also possible to amend this configuration with factory configurations for: ## Content Disposition Filter -The Content Disposition Filter is a Sling request/forward filter that adds `Content-Disposition: attachment` for configured resource paths on `GET` and `HEAD` requests. It supports explicit path includes, prefix includes (`*` suffix), exclusions, and optional all-path mode. +The Content Disposition Filter is a Sling request/forward filter that adds `Content-Disposition: attachment` for configured resource paths on `GET` and `HEAD` requests. It supports exact path includes, prefix includes (`*` suffix), exclusions, and optional all-path mode. -The header is only added for resources that contain `jcr:data` directly or below `jcr:content/jcr:data`. +The header is only added for resources that contain `jcr:data` directly or below `jcr:content/jcr:data`. Per-path content type lists are interpreted as excluded content types for that path. Configuration PID: `org.apache.sling.security.impl.ContentDispositionFilter`
