build: Maven Central publishing plumbing

README.md

@@ -211,6 +211,7 @@ mvn test -pl aauth -am -Dtest=PythonInteropTest \
 - Reference implementation: [aauth-python-library](https://github.com/christian-posta/aauth-python-library)
 
 Implementation plan and progress log: [docs/PLAN.md](docs/PLAN.md), [docs/PROGRESS.md](docs/PROGRESS.md).
+Publishing to Maven Central: [RELEASING.md](RELEASING.md).
 
 ## License
 

RELEASING.md

@@ -0,0 +1,83 @@
+# Releasing to Maven Central
+
+The build is already wired for Central publishing (the `release` Maven profile adds sources
+and javadoc jars, GPG signing, and the Central Portal upload). Two one-time setup steps must
+be done by a human; after that, releases are a short procedure.
+
+## One-time setup
+
+### 1. Central Portal account + namespace
+
+1. Sign in at <https://central.sonatype.com> **with your GitHub account** (`marcofanti`).
+2. Signing in with GitHub automatically verifies the `io.github.marcofanti` namespace.
+3. Generate a **user token** (Account → Generate User Token) and put it in
+   `~/.m2/settings.xml`:
+
+   ```xml
+   <settings>
+     <servers>
+       <server>
+         <id>central</id>
+         <username><!-- token username --></username>
+         <password><!-- token password --></password>
+       </server>
+     </servers>
+   </settings>
+   ```
+
+   The `id` must be `central` (it matches `publishingServerId` in the parent POM).
+   Never commit these credentials.
+
+### 2. GPG signing key
+
+```bash
+gpg --gen-key                          # name: Marco Fanti, email: your GitHub email
+gpg --list-keys --keyid-format long    # note the key ID (after ed25519/ or rsa4096/)
+gpg --keyserver keyserver.ubuntu.com --send-keys <KEY_ID>
+```
+
+Central verifies signatures against public keyservers; sending the key once is enough.
+The `maven-gpg-plugin` uses `gpg-agent`, so you'll be prompted for the passphrase on the
+first signing of a session.
+
+## Release procedure
+
+```bash
+# 1. Start from a green main
+git checkout main && git pull && mvn verify
+
+# 2. Set the release version (drop -SNAPSHOT) in all three POMs
+mvn versions:set -DnewVersion=0.1.0 && mvn versions:commit
+
+# 3. Commit and tag (via PR per repo convention, or directly if you prefer for releases)
+git commit -am "release: 0.1.0" && git tag v0.1.0
+
+# 4. Build, sign and upload to the Central Portal
+mvn clean deploy -Prelease
+
+# 5. Publish: the artifacts land in https://central.sonatype.com/publishing as a
+#    validated deployment — press "Publish" there. (To skip the manual press, add
+#    <autoPublish>true</autoPublish> to the central-publishing-maven-plugin config.)
+
+# 6. Bump back to the next snapshot and push
+mvn versions:set -DnewVersion=0.2.0-SNAPSHOT && mvn versions:commit
+git commit -am "chore: bump to 0.2.0-SNAPSHOT" && git push && git push --tags
+```
+
+Artifacts appear on Maven Central (search.maven.org) within an hour of publishing:
+
+```xml
+<dependency>
+  <groupId>io.github.marcofanti</groupId>
+  <artifactId>aauth</artifactId>          <!-- or aauth-signing for the signing layer only -->
+  <version>0.1.0</version>
+</dependency>
+```
+
+## Notes
+
+- `mvn verify -Prelease -Dgpg.skip=true` exercises the sources/javadoc jar generation
+  without needing the GPG key (useful as a pre-release smoke test; CI does not run the
+  release profile).
+- Javadoc runs with `doclint` on (missing-comment checks relaxed); a javadoc error fails
+  the release build rather than shipping a broken javadoc jar.

docs/PROGRESS.md

@@ -64,6 +64,10 @@ reference with no findings.
   to loopback (see `TestHosts`); CI runners fall back to `127.0.0.1`. First CI run failed on
   unresolvable lab hostnames; second run green.
 
+- **Maven Central plumbing added (2026-08-02)**: `<scm>` metadata plus a `release` profile
+  (sources/javadoc jars, GPG signing, central-publishing-maven-plugin). Manual steps
+  (Portal signup, GPG key) documented in RELEASING.md. Normal builds unaffected.
+
 ## Test fixtures
 
 Per user request (2026-07-30), test fixtures and examples use the local UMA lab hostnames

pom.xml

@@ -28,6 +28,13 @@
     </developer>
   </developers>
 
+  <scm>
+    <connection>scm:git:https://github.com/marcofanti/aauth-java-library.git</connection>
+    <developerConnection>scm:git:git@github.com:marcofanti/aauth-java-library.git</developerConnection>
+    <url>https://github.com/marcofanti/aauth-java-library</url>
+    <tag>HEAD</tag>
+  </scm>
+
   <modules>
     <module>aauth-signing</module>
     <module>aauth</module>
@@ -42,6 +49,10 @@
     <assertj.version>3.27.7</assertj.version>
 
     <maven-compiler-plugin.version>3.15.0</maven-compiler-plugin.version>
+    <maven-source-plugin.version>3.4.0</maven-source-plugin.version>
+    <maven-javadoc-plugin.version>3.12.0</maven-javadoc-plugin.version>
+    <maven-gpg-plugin.version>3.2.8</maven-gpg-plugin.version>
+    <central-publishing-maven-plugin.version>0.11.0</central-publishing-maven-plugin.version>
     <maven-surefire-plugin.version>3.5.6</maven-surefire-plugin.version>
     <maven-enforcer-plugin.version>3.6.3</maven-enforcer-plugin.version>
     <jacoco-maven-plugin.version>0.8.15</jacoco-maven-plugin.version>
@@ -201,4 +212,73 @@
       </plugin>
     </plugins>
   </build>
+
+  <profiles>
+    <!-- Maven Central release: sources + javadoc jars, GPG signing, Central Portal upload.
+         See RELEASING.md for the one-time account/key setup and the release procedure. -->
+    <profile>
+      <id>release</id>
+      <build>
+        <plugins>
+          <plugin>
+            <groupId>org.apache.maven.plugins</groupId>
+            <artifactId>maven-source-plugin</artifactId>
+            <version>${maven-source-plugin.version}</version>
+            <executions>
+              <execution>
+                <id>attach-sources</id>
+                <goals>
+                  <goal>jar-no-fork</goal>
+                </goals>
+              </execution>
+            </executions>
+          </plugin>
+          <plugin>
+            <groupId>org.apache.maven.plugins</groupId>
+            <artifactId>maven-javadoc-plugin</artifactId>
+            <version>${maven-javadoc-plugin.version}</version>
+            <configuration>
+              <doclint>all,-missing</doclint>
+            </configuration>
+            <executions>
+              <execution>
+                <id>attach-javadocs</id>
+                <goals>
+                  <goal>jar</goal>
+                </goals>
+              </execution>
+            </executions>
+          </plugin>
+          <plugin>
+            <groupId>org.apache.maven.plugins</groupId>
+            <artifactId>maven-gpg-plugin</artifactId>
+            <version>${maven-gpg-plugin.version}</version>
+            <executions>
+              <execution>
+                <id>sign-artifacts</id>
+                <phase>verify</phase>
+                <goals>
+                  <goal>sign</goal>
+                </goals>
+                <configuration>
+                  <!-- Prompting is impossible in CI/agent runs; use gpg-agent or a passphrase
+                       from settings.xml. -->
+                  <bestPractices>true</bestPractices>
+                </configuration>
+              </execution>
+            </executions>
+          </plugin>
+          <plugin>
+            <groupId>org.sonatype.central</groupId>
+            <artifactId>central-publishing-maven-plugin</artifactId>
+            <version>${central-publishing-maven-plugin.version}</version>
+            <extensions>true</extensions>
+            <configuration>
+              <publishingServerId>central</publishingServerId>
+            </configuration>
+          </plugin>
+        </plugins>
+      </build>
+    </profile>
+  </profiles>
 </project>