From e5a31b87eb7d023bcfe4e2e281f4d906499ef183 Mon Sep 17 00:00:00 2001
From: Rob Bygrave <robin.bygrave@gmail.com>
Date: Tue, 25 Mar 2025 20:20:01 +1300
Subject: [PATCH] Add README for oauth2 core and helidon JwtAuthFilter

---
 avaje-oauth2-core/README.md              | 37 ++++++++++++++++++++++++
 avaje-oauth2-helidon-jwtfilter/README.md | 35 ++++++++++++++++++++++
 2 files changed, 72 insertions(+)
 create mode 100644 avaje-oauth2-core/README.md
 create mode 100644 avaje-oauth2-helidon-jwtfilter/README.md

diff --git a/avaje-oauth2-core/README.md b/avaje-oauth2-core/README.md
new file mode 100644
index 0000000..1f79902
--- /dev/null
+++ b/avaje-oauth2-core/README.md
@@ -0,0 +1,37 @@
+# avaje-oauth2-core
+
+Provides core OAuth2 features.
+
+
+### JwtVerifier
+
+JwtVerifier verifies a Signed JWT Access token is valid.
+
+```java
+String issuer = "https://cognito-idp.REGION.amazonaws.com/REGION_FOO";
+
+JwtVerifier jwtVerifier = JwtVerifier.builder()
+    .issuer(issuer)
+    .build();
+
+String rawAccessToken = ...;
+
+try {
+    // verify that the raw access token is valid, and return
+    // the parsed AccessToken
+    AccessToken accessToken = verifier.verifyAccessToken(rawAccessToken);
+} catch (JwtVerifyException exception) {
+    // invalid access token
+}
+```
+
+
+### SignedJwt
+
+Parse a SignedJwt.
+
+```java
+String rawToken = "eyJraWQiOiJqR3lQcEc4MDNTc1ZmSjRtZERkVktE...";
+SignedJwt token = SignedJwt.parse(rawToken);
+
+```
\ No newline at end of file
diff --git a/avaje-oauth2-helidon-jwtfilter/README.md b/avaje-oauth2-helidon-jwtfilter/README.md
new file mode 100644
index 0000000..7b978bf
--- /dev/null
+++ b/avaje-oauth2-helidon-jwtfilter/README.md
@@ -0,0 +1,35 @@
+
+# avaje-oauth2-helidon-jwtfilter
+
+Provides a Helidon Filter that ensures a valid Signed JWT access token
+is supplied as a `Authorization` `Bearer` http header.
+
+### Typical use
+
+- Build a JwtVerifier typically using an issuer endpoint
+- Build a JwtAuthFilter 
+- Register the JwtAuthFilter as a Filter with the Helidon Webserver
+
+```java
+String issuer = "https://cognito-idp.REGION.amazonaws.com/REGION_FOO";
+
+JwtVerifier jwtVerifier = JwtVerifier.builder()
+    .issuer(issuer)
+    .build();
+
+JwtAuthFilter filter = JwtAuthFilter.builder()
+    .permit("/health")
+    .permit("/ping")
+    .verifier(jwtVerifier)
+    .build();
+```
+
+## Dependency
+
+```xml
+<dependency>
+    <groupId>io.avaje</groupId>
+    <artifactId>avaje-oauth2-helidon-jwtfilter</artifactId>
+    <version>0.1</version>
+</dependency>
+```