feat: add push identity resolution, IdentityVerificationHook, and Bitbucket credential rewriting

Implements push identity resolution across all supported providers (#41):

- New `TokenIdentityProvider` interface with `fetchScmIdentity(pushUsername, token)` — GitHub,
  GitLab, and Codeberg ignore the username; Bitbucket uses it as the account email for Basic auth.
- `TokenPushIdentityResolver` resolves a push user via the provider API then matches against
  `user_scm_identities` (with email fallback).
- `IdentityVerificationHook` (store-and-forward) and `IdentityVerificationFilter` (transparent
  proxy) check that every pushed commit's author/committer email is registered to the push user.
  Configurable as STRICT / WARN / OFF via `commit.identity-verification`.

Bitbucket identity resolution and credential rewriting:
- Bitbucket does not enforce the git push username, so the proxy convention is that the HTTP
  Basic-auth username must be the user's Bitbucket account email. The API returns an
  auto-generated `username` that Bitbucket's git endpoint requires; the proxy rewrites outbound
  credentials from `email:token` to `username:token` before forwarding.
- Transparent proxy: `BitbucketIdentityFilter` (order 148) resolves the upstream username and
  stores it on `GitRequestDetails`; `PushFinalizerFilter` rewrites the `Authorization` header via
  `HttpServletRequestWrapper` on allowed pushes.
- Store-and-forward: `BitbucketCredentialRewriteHook` (order 148) writes the resolved username to
  the in-memory JGit repo config; `ForwardingPostReceiveHook` reads it and opens the upstream
  transport with rewritten credentials.

Also includes filter chain cleanup, user store refactors, and additional filter tests.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: coopernetes

build.gradle

@@ -12,7 +12,7 @@ ext {
     jgitVersion = '7.6.0.202603022253-r'
 
     // HTTP
-    apacheHttpVersion = '4.5.14'
+    apacheHttpClientVersion = '5.6'
 
     // Jetty / Servlet
     jettyVersion = '12.1.8'

docs/CONFIGURATION.md

@@ -98,16 +98,28 @@ providers:
   bitbucket:
     enabled: true
 
-  # Custom provider — requires explicit URI
-  internal-gitlab:
+  # Self-hosted GitHub Enterprise Server — name contains "github" so type is inferred
+  internal-github:
     enabled: true
-    servlet-path: /enterprise
-    uri: https://gitlab.internal.example.com
+    uri: https://github.corp.example.com
 
-  debian-gitlab:
+  # Self-hosted instance with an arbitrary name — use 'type' to select the provider implementation
+  my-internal-server:
     enabled: true
-    servlet-path: /debian
-    uri: https://salsa.debian.org/
+    type: github          # uses GitHubProvider (identity resolution, GHES API path logic, etc.)
+    uri: https://github.corp.example.com
+
+  # Self-hosted Forgejo instance
+  my-forgejo:
+    enabled: true
+    type: forgejo         # also accepts: codeberg
+    uri: https://forge.internal.example.com
+
+  # Bitbucket Data Center (self-hosted)
+  acme-bitbucket:
+    enabled: true
+    type: bitbucket
+    uri: https://bitbucket.acme.com
 ```
 
 ### Provider properties
@@ -117,6 +129,25 @@ providers:
 | `enabled` | boolean | `true` | Whether the provider is active |
 | `servlet-path` | string | `""` | Additional URL prefix for this provider |
 | `uri` | string | _(built-in default)_ | Upstream base URI (required for custom providers) |
+| `type` | string | _(inferred from name)_ | Provider implementation to use: `github`, `gitlab`, `bitbucket`, `codeberg`, `forgejo`. Set this when the provider name does not contain the type keyword. |
+
+When `type` (or the provider name) matches a known implementation, the full typed provider is used — including its API URL logic, identity resolution, and (for Bitbucket) credential rewriting. A custom `uri` overrides only the upstream address; all other behaviour is inherited from the provider type.
+
+### Bitbucket identity resolution
+
+Bitbucket does not enforce the git push username — only the token is validated. To enable identity resolution (required for push permission checks and commit identity verification), the proxy adopts the convention that the **HTTP Basic-auth username in the remote URL must be the user's Bitbucket account email address**.
+
+Configure the remote URL like this:
+
+```
+https://<email>:<api-token>@bitbucket.org/<workspace>/<repo>.git
+```
+
+The proxy calls `GET /2.0/user` using those credentials to look up the user's Bitbucket `username` (the auto-generated URL-safe identifier, e.g. `a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6`). It then rewrites the outbound credentials to `username:token` before forwarding the push to Bitbucket — this is necessary because Bitbucket's git endpoint only accepts the internal username, not an email address.
+
+**Required API token scopes:** `read:user:bitbucket` and `write:repository:bitbucket`.
+
+> **M&A / private server use case:** This same mechanism works for self-hosted Bitbucket Data Center instances. Set `uri` to your internal Bitbucket URL and the proxy will route and rewrite credentials accordingly, making it straightforward to gate pushes to acquired-company repositories during an integration period.
 
 ## Commit validation
 

jgit-proxy-core/build.gradle

@@ -51,8 +51,7 @@ dependencies {
     api "org.eclipse.jgit:org.eclipse.jgit.http.server:${jgitVersion}"
 
     // HTTP Client
-    implementation "org.apache.httpcomponents:httpclient:${apacheHttpVersion}"
-    
+    implementation "org.apache.httpcomponents.client5:httpclient5-fluent:${apacheHttpClientVersion}"
 
     // Jackson for JSON — BOM pins all jackson-* modules to the same version
     api platform("tools.jackson:jackson-bom:${jacksonBomVersion}")

jgit-proxy-core/src/main/java/org/finos/gitproxy/config/CommitConfig.java

@@ -11,6 +11,33 @@
 @Builder
 public class CommitConfig {
 
+    /** Controls whether commit identity is verified against the authenticated push user. */
+    public enum IdentityVerificationMode {
+        /** Block the push when any commit author/committer email is not registered to the push user. */
+        STRICT,
+        /** Warn the push user but allow the push through. Default. */
+        WARN,
+        /** Skip identity verification entirely. */
+        OFF;
+
+        public static IdentityVerificationMode fromString(String value) {
+            if (value == null) return WARN;
+            return switch (value.trim().toLowerCase()) {
+                case "strict" -> STRICT;
+                case "off" -> OFF;
+                default -> WARN;
+            };
+        }
+    }
+
+    /**
+     * Whether to verify that commit author/committer emails are registered to the authenticated push user. When users
+     * are configured, {@code WARN} is the default — mismatches produce a warning but do not block. {@code STRICT}
+     * blocks the push. {@code OFF} skips the check entirely.
+     */
+    @Builder.Default
+    private IdentityVerificationMode identityVerification = IdentityVerificationMode.WARN;
+
     /** Configuration for author email validation. */
     @Builder.Default
     private AuthorConfig author = AuthorConfig.builder().build();

jgit-proxy-core/src/main/java/org/finos/gitproxy/git/BitbucketCredentialRewriteHook.java

@@ -0,0 +1,67 @@
+package org.finos.gitproxy.git;
+
+import java.util.Collection;
+import java.util.Optional;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.eclipse.jgit.transport.ReceiveCommand;
+import org.eclipse.jgit.transport.ReceivePack;
+import org.finos.gitproxy.provider.BitbucketProvider;
+import org.finos.gitproxy.provider.client.ScmUserInfo;
+
+/**
+ * Pre-receive hook that resolves the Bitbucket push user's upstream username and stores it in the repository config
+ * ({@code gitproxy.upstreamUser}) for use by {@link ForwardingPostReceiveHook}.
+ *
+ * <p>Bitbucket does not validate the HTTP Basic-auth username on git pushes — only the token is checked. The proxy
+ * convention is that the username field carries the user's Bitbucket account email. This hook calls {@code GET
+ * /2.0/user} using that email and the push token to retrieve the auto-generated {@code username} field that Bitbucket
+ * recognises for git authentication.
+ *
+ * <p>{@link ForwardingPostReceiveHook} reads {@code gitproxy.upstreamUser} and rewrites the outbound credentials from
+ * {@code email:token} to {@code username:token} before pushing to Bitbucket upstream.
+ *
+ * <p>Runs at order 148, before {@link CheckUserPushPermissionHook} (150).
+ */
+@Slf4j
+@RequiredArgsConstructor
+public class BitbucketCredentialRewriteHook implements GitProxyHook {
+
+    private static final int ORDER = 148;
+
+    private final BitbucketProvider provider;
+
+    @Override
+    public int getOrder() {
+        return ORDER;
+    }
+
+    @Override
+    public String getName() {
+        return "bitbucketCredentialRewrite";
+    }
+
+    @Override
+    public void onPreReceive(ReceivePack rp, Collection<ReceiveCommand> commands) {
+        var repo = rp.getRepository();
+        String pushEmail = repo.getConfig().getString("gitproxy", null, "pushUser");
+        String pushToken = repo.getConfig().getString("gitproxy", null, "pushToken");
+
+        if (pushEmail == null || pushToken == null) {
+            log.debug("No push credentials in repo config — skipping Bitbucket upstream username resolution");
+            return;
+        }
+
+        Optional<ScmUserInfo> identity = provider.fetchScmIdentity(pushEmail, pushToken);
+        if (identity.isEmpty()) {
+            log.debug(
+                    "Could not resolve Bitbucket upstream username for '{}' — credentials will be forwarded as-is",
+                    pushEmail);
+            return;
+        }
+
+        String upstreamUser = identity.get().login();
+        repo.getConfig().setString("gitproxy", null, "upstreamUser", upstreamUser);
+        log.debug("Stored Bitbucket upstream username '{}' for push email '{}'", upstreamUser, pushEmail);
+    }
+}

jgit-proxy-core/src/main/java/org/finos/gitproxy/git/CheckUserPushPermissionHook.java

@@ -12,6 +12,7 @@
 import org.eclipse.jgit.transport.ReceivePack;
 import org.finos.gitproxy.db.model.PushStep;
 import org.finos.gitproxy.db.model.StepStatus;
+import org.finos.gitproxy.provider.GitProxyProvider;
 import org.finos.gitproxy.service.PushIdentityResolver;
 import org.finos.gitproxy.service.UserAuthorizationService;
 import org.finos.gitproxy.user.UserEntry;
@@ -32,27 +33,27 @@ public class CheckUserPushPermissionHook implements GitProxyHook {
     private final UserAuthorizationService userAuthorizationService;
     private final ValidationContext validationContext;
     private final PushContext pushContext;
-    private final String providerName;
+    private final GitProxyProvider provider;
 
     public CheckUserPushPermissionHook(
             PushIdentityResolver identityResolver,
             UserAuthorizationService userAuthorizationService,
             ValidationContext validationContext,
             PushContext pushContext) {
-        this(identityResolver, userAuthorizationService, validationContext, pushContext, "");
+        this(identityResolver, userAuthorizationService, validationContext, pushContext, (GitProxyProvider) null);
     }
 
     public CheckUserPushPermissionHook(
             PushIdentityResolver identityResolver,
             UserAuthorizationService userAuthorizationService,
             ValidationContext validationContext,
             PushContext pushContext,
-            String providerName) {
+            GitProxyProvider provider) {
         this.identityResolver = identityResolver;
         this.userAuthorizationService = userAuthorizationService;
         this.validationContext = validationContext;
         this.pushContext = pushContext;
-        this.providerName = providerName != null ? providerName : "";
+        this.provider = provider;
     }
 
     @Override
@@ -82,9 +83,8 @@ public void onPreReceive(ReceivePack rp, Collection<ReceiveCommand> commands) {
         }
 
         // Resolve identity: who is the person behind these credentials?
-        Optional<UserEntry> resolved = identityResolver != null
-                ? identityResolver.resolve(providerName, pushUser, pushToken)
-                : Optional.empty();
+        Optional<UserEntry> resolved =
+                identityResolver != null ? identityResolver.resolve(provider, pushUser, pushToken) : Optional.empty();
 
         if (resolved.isEmpty()) {
             log.warn("Push user '{}' could not be resolved to a registered proxy user", pushUser);

jgit-proxy-core/src/main/java/org/finos/gitproxy/git/ForwardingPostReceiveHook.java

@@ -49,6 +49,16 @@ public void onPostReceive(ReceivePack rp, Collection<ReceiveCommand> commands) {
         }
 
         Repository repo = rp.getRepository();
+
+        // If BitbucketCredentialRewriteHook resolved an upstream username, use it instead of the push email.
+        String upstreamUser = repo.getConfig().getString("gitproxy", null, "upstreamUser");
+        CredentialsProvider effectiveCreds = credentials;
+        if (upstreamUser != null) {
+            String pushToken = repo.getConfig().getString("gitproxy", null, "pushToken");
+            effectiveCreds = new UsernamePasswordCredentialsProvider(upstreamUser, pushToken != null ? pushToken : "");
+            log.debug("Using Bitbucket upstream username '{}' for forwarding credentials", upstreamUser);
+        }
+
         String upstreamUrl = repo.getConfig().getString("gitproxy", null, "upstreamUrl");
 
         if (upstreamUrl == null) {
@@ -72,7 +82,7 @@ public void onPostReceive(ReceivePack rp, Collection<ReceiveCommand> commands) {
 
         try {
             URIish upstream = new URIish(upstreamUrl);
-            forwardFailed = pushToUpstream(rp, repo, upstream, accepted, logs);
+            forwardFailed = pushToUpstream(rp, repo, upstream, accepted, logs, effectiveCreds);
         } catch (Exception e) {
             rp.sendMessage(color(RED, sym(CROSS_MARK) + "  ERROR forwarding to upstream: " + e.getMessage()));
             log.error("Failed to push to upstream {}", upstreamUrl, e);
@@ -91,13 +101,18 @@ public void onPostReceive(ReceivePack rp, Collection<ReceiveCommand> commands) {
 
     /** Returns true if any ref failed to forward. */
     private boolean pushToUpstream(
-            ReceivePack rp, Repository repo, URIish upstream, List<ReceiveCommand> commands, List<String> logs)
+            ReceivePack rp,
+            Repository repo,
+            URIish upstream,
+            List<ReceiveCommand> commands,
+            List<String> logs,
+            CredentialsProvider creds)
             throws Exception {
 
         boolean anyFailed = false;
         try (Transport transport = Transport.open(repo, upstream)) {
-            if (credentials != null) {
-                transport.setCredentialsProvider(credentials);
+            if (creds != null) {
+                transport.setCredentialsProvider(creds);
             }
 
             List<RemoteRefUpdate> updates = buildRefUpdates(repo, commands);

jgit-proxy-core/src/main/java/org/finos/gitproxy/git/GitRequestDetails.java

@@ -29,7 +29,14 @@ public class GitRequestDetails {
     private String commitFrom; // Old ref SHA from the packet line (the push range start)
     private String commitTo; // New ref SHA from the packet line (the push range end)
     private List<Commit> pushedCommits = new ArrayList<>(); // All commits received in this push
-    private GitProxyProvider provider;
+    private GitProxyProvider provider; // this should never be null
+    /**
+     * Provider-specific upstream username to use when forwarding the push. Set by {@code BitbucketIdentityFilter}
+     * (transparent proxy) or {@code BitbucketCredentialRewriteHook} (store-and-forward) when the push username needs
+     * rewriting before forwarding. {@code null} for all non-Bitbucket providers.
+     */
+    private String upstreamUsername;
+
     private List<GitProxyFilter> filters = new ArrayList<>();
     private List<PushStep> steps = new ArrayList<>(); // Filter/hook results for audit trail
     private GitResult result = GitResult.PENDING;