This is an automated email from the ASF dual-hosted git repository.
cziegeler pushed a commit to branch master
in repository
https://gitbox.apache.org/repos/asf/sling-org-apache-sling-security.git
The following commit(s) were added to refs/heads/master by this push:
new 2f6df13 docs: add AGENTS.md, CLAUDE.md, and expand README (#12)
2f6df13 is described below
commit 2f6df130f1ec67985af35245af49e189ce6efbe6
Author: Carsten Ziegeler <[email protected]>
AuthorDate: Tue Jun 2 08:36:12 2026 +0200
docs: add AGENTS.md, CLAUDE.md, and expand README (#12)
Co-authored-by: Maia <maia@noreply>
---
AGENTS.md | 78 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
CLAUDE.md | 1 +
README.md | 71 +++++++++++++++++++++++++++++++++++++++++++++++----------
3 files changed, 138 insertions(+), 12 deletions(-)
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..3e2a8de
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,78 @@
+# 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 [...]
+
+# 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 a single test method:** `mvn test
-Dtest=ReferrerFilterTest#testMethodName`
+- **Lint / format check (Spotless via parent POM):** `mvn spotless:check`
+- **Apply formatting:** `mvn spotless:apply`
+- **License header check:** `mvn rat:check`
+- **OSGi baseline check:** `mvn baseline:check`
+- **Release:** follow [Apache Sling release
process](https://sling.apache.org/contributing.html)
+
+No dev server — this is an OSGi bundle deployed to a running Sling/Felix
instance.
+
+# Project Layout
+
+```
+pom.xml Maven build descriptor
+bnd.bnd OSGi bundle manifest overrides
+src/
+ main/java/org/apache/sling/security/impl/
+ ReferrerFilter.java CSRF filter (OSGi Preprocessor)
+ ReferrerFilterAmendment.java Interface for referrer allowlist
extensions
+ ReferrerFilterAmendmentImpl.java Default amendment implementation
+ ContentDispositionFilter.java Content-Disposition enforcement filter
+ ContentDispositionFilterConfiguration.java Metatype config interface
+ test/java/org/apache/sling/security/impl/
+ ReferrerFilterTest.java
+ ContentDispositionFilterTest.java
+target/ Build output (generated, not committed)
+```
+
+All production code lives under `org.apache.sling.security.impl`. There are no
public API packages exported — this bundle is purely internal implementation.
+
+# Development Patterns & Constraints
+
+- **Java version:** 11 (source and target)
+- **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.
+- **License header:** Every `.java` file must carry the Apache 2.0 license
header. Run `mvn rat:check` to verify.
+- **No public API exports:** `bnd.bnd` sets `Import-Package` with
`org.apache.sling.*` as optional. Do not add new exported packages without
discussion.
+- **Servlet API:** `javax.servlet` (not `jakarta.servlet`) — dependency is
`javax.servlet-api`.
+- **Logging:** SLF4J only (`org.slf4j`). No `java.util.logging` or Log4j
direct usage.
+- **Dependencies:** Minimize additions. All compile-time deps must be
`provided` scope (OSGi container supplies them). Test deps use `test` scope.
+
+# Git Workflow
+
+- **Default branch:** `master`
+- **Commit messages:** Reference JIRA issue when applicable (`SLING-XXXXX -
description`). Use imperative mood.
+- **Branching:** Feature branches are typical; branch names are free-form.
+- **PRs:** Require passing CI (Jenkins). License and baseline checks run as
part of CI.
+- **No force pushes** to `master` (enforced by repo policy).
+- **Tags:** Release tags follow `org.apache.sling.security-X.Y.Z` (set by
`maven-release-plugin`).
+
+# Testing Guidelines
+
+- **Framework:** JUnit 4 (`junit:junit`), with Mockito 4 and JMock for mocking.
+- **Test location:** `src/test/java/org/apache/sling/security/impl/`
+- **Naming:** Test class name = production class name + `Test`. Test methods
use descriptive names.
+- **Coverage:** No enforced coverage threshold; aim to cover all filter logic
branches (allow/deny decisions).
+- **Run all tests:** `mvn test`
+- **Run one class:** `mvn test -Dtest=ContentDispositionFilterTest`
+- **Reports:** `target/surefire-reports/`
+
+# Gotchas
+
+- `ReferrerFilter` is registered as an OSGi `Preprocessor` (HTTP Whiteboard),
not a standard Sling filter — it runs before Sling servlet resolution.
+- 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.
+- 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.
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..9a80b01
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1 @@
+read @AGENTS.md
diff --git a/README.md b/README.md
index e0cf5a5..9829c4a 100644
--- a/README.md
+++ b/README.md
@@ -6,22 +6,40 @@
This module is part of the [Apache Sling](https://sling.apache.org) project.
-The Apache Sling Security module provides CSRF protection through a filter
checking the referrer and a content disposition filter. This OSGi bundle can be
used as a standalone bundle outside of Apache Sling - in that case only the
referrer check functionality is available as the content disposition filter
depends on the Apache Sling Framework
+The Apache Sling Security module provides:
-## Referrer Filter (CSRF Protection)
+- CSRF protection through the **Referrer Filter**
+- download hardening through the **Content Disposition Filter**
-Configuring the Apache Sling Referrer Filter involves setting up an OSGi
configuration to manage which referrers are allowed to access your application.
Here are some of the options:
+This OSGi bundle can be used as a standalone bundle outside of Apache Sling.
In that case, only the Referrer Filter functionality is available, as the
Content Disposition Filter depends on the Apache Sling API.
-- **Allow Empty**: Determines if requests with empty or missing referrer
headers are allowed. This should typically be set to `false` for security
reasons.
-- **Allow Hosts**: Specifies a list of allowed hosts for the referrer. These
are matched against the full referrer URL.
-- **Allow Regexp Hosts**: Allows using regular expressions to match referrer
hosts.
-- **Filter Methods**: Specifies which HTTP methods (e.g., POST, PUT, DELETE)
are filtered by the Referrer Filter.
-- **Exclude Regexp User Agents**: Allows excluding certain user agents from
referrer checks.
-- **Exclude Paths**: Specifies paths that should not be checked for referrers.
+## Requirements
-### Sample Configuration
+- Java 11+
+- Maven (the project inherits build plugins and checks from Sling parent POM
v66)
-The filter can be configured through an OSGi configuration for the PID
`org.apache.sling.security.impl.ReferrerFilter`. This is a sample configuration
in JSON format:
+## Build and test
+
+- Build: `mvn clean install`
+- Build without tests: `mvn clean install -DskipTests`
+- Run tests: `mvn test`
+
+## Referrer Filter (CSRF protection)
+
+The Referrer Filter is registered as an OSGi HTTP Whiteboard `Preprocessor`
and checks modification requests from browsers.
+
+Configuration PID: `org.apache.sling.security.impl.ReferrerFilter`
+
+Main configuration options:
+
+- **Allow Empty** (`allow.empty`)
+- **Allow Hosts** (`allow.hosts`)
+- **Allow Regexp Host** (`allow.hosts.regexp`)
+- **Filter Methods** (`filter.methods`)
+- **Exclude Regexp User Agent** (`exclude.agents.regexp`)
+- **Exclude Paths** (`exclude.paths`)
+
+### Sample configuration
```json
{
@@ -34,7 +52,11 @@ The filter can be configured through an OSGi configuration
for the PID `org.apac
}
```
-In addition it is possible to amend the configuration by additional OSGi
factory configurations for the factory PID
`org.apache.sling.security.impl.ReferrerFilterAmendmentImpl`. This is a sample
configuration in JSON format:
+It is also possible to amend this configuration with factory configurations
for:
+
+- Factory PID: `org.apache.sling.security.impl.ReferrerFilterAmendmentImpl`
+
+### Sample amendment configuration
```json
{
@@ -45,4 +67,29 @@ In addition it is possible to amend the configuration by
additional OSGi factory
}
```
+## Content Disposition Filter
+The Content Disposition Filter adds `Content-Disposition: attachment` for
configured Sling resource paths (for `GET` and `HEAD` requests), with support
for explicit path includes, prefix includes, exclusions, and optional all-path
mode.
+
+Configuration PID: `org.apache.sling.security.impl.ContentDispositionFilter`
+
+Main configuration options:
+
+- **Included Resource Paths & Content Types**
(`sling.content.disposition.paths`)
+- **Excluded Resource Paths** (`sling.content.disposition.excluded.paths`)
+- **Enable For All Resource Paths** (`sling.content.disposition.all.paths`)
+
+### Sample configuration
+
+```json
+{
+ "sling.content.disposition.paths": [
+ "/content/secure/*",
+ "/content/files/report.pdf:text/html,text/plain"
+ ],
+ "sling.content.disposition.excluded.paths": [
+ "/content/secure/preview"
+ ],
+ "sling.content.disposition.all.paths": false
+}
+```
