feat: add UrlSigner interface for customizable URL signing

AGENTS.md

@@ -0,0 +1,13 @@
+# AGENTS.md
+
+## Java Commands
+
+All `java`, `javac`, and related JVM commands must be prefixed with `mise exec --` to ensure the correct Java version (as specified by [mise](https://mise.jdx.dev/)) is used. Examples:
+
+```bash
+mise exec -- java -version
+mise exec -- ./gradlew build
+mise exec -- ./gradlew test
+```
+
+This applies to any direct `java` invocation and to any tool that shells out to the JVM.

README.md

@@ -32,6 +32,7 @@ Made with :heart: by Widen.
   * [UrlBuilderQueryParamsTest](/src/test/java/com/widen/urlbuilder/UrlBuilderQueryParamsTest.java) - query parameters
   * [UrlBuilderPortSslTest](/src/test/java/com/widen/urlbuilder/UrlBuilderPortSslTest.java) - port and SSL
   * [UrlBuilderModesTest](/src/test/java/com/widen/urlbuilder/UrlBuilderModesTest.java) - output modes
+  * [UrlBuilderSigningTest](/src/test/java/com/widen/urlbuilder/UrlBuilderSigningTest.java) - URL signing
 
 ## Installation
 
@@ -180,6 +181,123 @@ new CloudfrontUrlBuilder("d1234.cloudfront.net", "files/document.pdf", "APKAEIBA
     .toString()
 ```
 
+## URL Signing
+
+UrlBuilder supports signing URLs during generation using the `UrlSigner` interface. This is useful for implementing HMAC signatures, RSA signing (like CloudFront), or other URL signing schemes.
+
+The `sign` method receives a `SigningContext` and returns a `Map<String, String>`. Each key/value pair in that map is appended as a query parameter to the final generated URL.
+
+### Basic Usage
+
+Sign URLs using a lambda function:
+
+```java
+import java.util.Collections;
+
+String SECRET_KEY = "my-secret-key";
+
+UrlBuilder builder = new UrlBuilder("cdn.example.com", "/videos/movie.mp4");
+builder.addParameter("user", "john");
+builder.usingUrlSigner(context -> {
+    // NOTE: use a strong hash like HmacSHA256 in production
+    String signature = Integer.toHexString((context.getUrl() + SECRET_KEY).hashCode());
+    return Collections.singletonMap("signature", signature);
+});
+String signedUrl = builder.toString();
+
+// Result: http://cdn.example.com/videos/movie.mp4?user=john&signature=abc123...
+```
+
+### Reusable Signers
+
+Create reusable signer classes:
+
+```java
+public class HmacUrlSigner implements UrlSigner {
+    private final String secretKey;
+
+    public HmacUrlSigner(String secretKey) {
+        this.secretKey = secretKey;
+    }
+
+    @Override
+    public Map<String, String> sign(SigningContext context) {
+        String signature = hmacSha256(context.getUrl(), secretKey);
+
+        Map<String, String> params = new HashMap<>();
+        params.put("signature", signature);
+        params.put("timestamp", String.valueOf(System.currentTimeMillis() / 1000));
+        return params;
+    }
+}
+
+// Usage
+HmacUrlSigner signer = new HmacUrlSigner("my-secret");
+UrlBuilder builder = new UrlBuilder("cdn.example.com", "/media/video.mp4");
+builder.usingUrlSigner(signer);
+String signedUrl = builder.toString();
+```
+
+### Expiring URLs
+
+Create signed URLs with expiration:
+
+```java
+public class ExpiringHmacSigner implements UrlSigner {
+    private final String secretKey;
+    private final long expirationSeconds;
+
+    public ExpiringHmacSigner(String secretKey, long expirationSeconds) {
+        this.secretKey = secretKey;
+        this.expirationSeconds = expirationSeconds;
+    }
+
+    @Override
+    public Map<String, String> sign(SigningContext context) {
+        long expiresAt = System.currentTimeMillis() / 1000 + expirationSeconds;
+
+        // Sign URL + expiration
+        String toSign = context.getUrl() + expiresAt;
+        String signature = hmacSha256(toSign, secretKey);
+
+        Map<String, String> params = new LinkedHashMap<>();
+        params.put("expires", String.valueOf(expiresAt));
+        params.put("signature", signature);
+        return params;
+    }
+}
+
+// Create URL that expires in 1 hour
+ExpiringHmacSigner signer = new ExpiringHmacSigner("my-secret", 3600);
+UrlBuilder builder = new UrlBuilder("api.example.com", "/v1/data");
+builder.usingUrlSigner(signer);
+String signedUrl = builder.toString();
+```
+
+### Signing Context
+
+The `SigningContext` provides access to URL components:
+
+- `getUrl()` - Complete unsigned URL (what you typically sign)
+- `getProtocol()` - Protocol (http/https)
+- `getHostname()` - Hostname
+- `getPort()` - Port number or -1
+- `getEncodedPath()` - URL-encoded path
+- `getEncodedQuery()` - URL-encoded query string
+- `getFragment()` - Fragment (not typically signed)
+- `isSsl()` - Whether using HTTPS
+- `getGenerationMode()` - URL generation mode
+
+### Best Practices
+
+1. **Keep signers stateless** - Signers should be thread-safe
+2. **Sign the complete URL** - Use `context.getUrl()` in most cases
+3. **Don't include fragments** - Fragments are client-side only
+4. **Use base64/hex encoding** - Signature values are not URL-encoded by default
+5. **Add expiration** - Prevent signature reuse with expiration timestamps
+
+See [`HmacSigningExampleTest`](/src/test/java/com/widen/urlbuilder/examples/HmacSigningExampleTest.java) for more examples.
+
 ## License
 
 Licensed under the Apache Version 2.0 license. See [the license file](LICENSE.md) for details.

build.gradle.kts

@@ -26,18 +26,23 @@ repositories {
 dependencies {
     implementation(libs.bundles.bouncycastle)
 
-    // JUnit 5
     testImplementation(platform(libs.junit.bom))
     testImplementation(libs.junit.jupiter)
     testRuntimeOnly(libs.junit.platform.launcher)
 
-    // Other test dependencies
     testImplementation(libs.commons.io)
     testImplementation(libs.slf4j.simple)
 }
 
 tasks.test {
     useJUnitPlatform()
+    testLogging {
+        events("started", "passed", "skipped", "failed")
+        exceptionFormat = org.gradle.api.tasks.testing.logging.TestExceptionFormat.FULL
+        showExceptions = true
+        showCauses = true
+        showStackTraces = true
+    }
 }
 
 nexusPublishing {