Merge branch 'feat/cedar-enforcement-logging'

Author: r-brown

.github/workflows/labs64io-ci.yml

@@ -40,7 +40,7 @@ jobs:
           pip install -q -e ".[dev]"
           pytest -q
 
-  # RFC-05 P1 — unified Cedar schema & policy gates. Edge + domain policies
+  # Edge + domain policies
   # validate against ONE shared schema (no-drift, F3), and a cross-tenant
   # isolation gate proves the tenant guard denies across-tenant access (F4/F8).
   cedar:

AGENTS.md

@@ -4,7 +4,7 @@ Guidance for AI agents working in this repository. Read this before making chang
 
 ## What this is
 
-Shared cross-service libraries for the Labs64.IO Ecosystem. Currently: the auth-context libraries (Java + Python), which parse, enforce and propagate the trusted gateway header contract, plus the unified Cedar authorization assets (RFC-05): the shared schema/policies in `auth-policy-cedar/` and the `@Authorize` Cedar domain PEP in the Java starter (`io.labs64.authcontext.cedar`, feature-flagged via `labs64.auth.cedar.*`, engine = optional `com.cedarpolicy:cedar-java:uber` dependency).
+Shared cross-service libraries for the Labs64.IO Ecosystem. Currently: the auth-context libraries (Java + Python), which parse, enforce and propagate the trusted gateway header contract, plus the unified Cedar authorization assets: the shared schema/policies in `auth-policy-cedar/` and the `@Authorize` Cedar domain PEP in the Java starter (`io.labs64.authcontext.cedar`, feature-flagged via `labs64.auth.cedar.*`, engine = optional `com.cedarpolicy:cedar-java:uber` dependency).
 
 ## Critical guardrails
 
@@ -22,7 +22,7 @@ Shared cross-service libraries for the Labs64.IO Ecosystem. Currently: the auth-
 |---|---|
 | `auth-context-java/` | `io.labs64:auth-context-spring-boot-starter` (incl. `@Authorize` Cedar domain PEP) |
 | `auth-context-python/` | `auth-context-python` (package `auth_context`) |
-| `auth-policy-cedar/` | THE shared Cedar schema + reference policies + `validate.sh` CI gate (RFC-05) |
+| `auth-policy-cedar/` | THE shared Cedar schema + reference policies + `validate.sh` CI gate |
 | `test-vectors/` | Canonical cross-language behavior vectors (headers + Cedar request construction) |
 
 ## Commands

auth-context-java/INTEGRATION.md

@@ -86,7 +86,7 @@ paths:
 ### Domain (Tier-2) resource authorization
 
 Declare `resource: <Type>` to have the operation authorized in-process by the
-module's `@Authorize` PEP against a typed Cedar resource (RFC-05 P3/P4). This is
+module's `@Authorize` PEP against a typed Cedar resource. This is
 the OpenAPI-native source for the generated domain policy set
 (`auth-policy-domain.cedar`): the preprocessor emits one `permit` keyed on the
 operationId, conditioned on the same `tenant`/`scopes`, plus one structural
@@ -132,7 +132,7 @@ Add three things to your `pom.xml`:
     <openapi.source>${project.basedir}/../your-api-module/src/main/resources/openapi/openapi-your-module.yaml</openapi.source>
     <openapi.generated>${project.build.directory}/generated-openapi/openapi-your-module.yaml</openapi.generated>
     <auth-policy.generated>${project.build.directory}/generated-resources/auth-policy.json</auth-policy.generated>
-    <!-- Cedar policies generated from x-labs64-auth (RFC-05 P2/P3/P4).
+    <!-- Cedar policies generated from x-labs64-auth.
          auth-policy.module MUST equal the module's gateway path prefix (e.g.
          payment-gateway) — it is baked into the Cedar resource ids.
          edge   → auth-policy.cedar        (Tier 1, served to the ACS/traefik)
@@ -360,11 +360,20 @@ endpoint in-cluster to build its edge authorization table.
 The same controller serves the build-generated **Tier-1 edge** Cedar policy set
 (`auth-policy.cedar`, emitted when the preprocessor is invoked with
 `--cedar-output` + `--module`) at `GET /.well-known/auth-policy.cedar`
-(text/plain; 404 when the module does not generate it). The authproxy fetches
-it alongside the JSON under live discovery — the identical distribution model
-— and evaluates it according to its `CEDAR_MODE` (RFC-05 P2). The `--module`
-name must equal the module's gateway path prefix (e.g. `payment-gateway`),
-because it is baked into the Cedar resource ids.
+(text/plain; 404 when the module does not generate it). Each generated permit
+also carries `@path`/`@method`/`@public`/`@tenantRequired`/`@scopes`
+annotations — the same fields `auth-policy.json`'s routes carry — so this one
+file doubles as the OpenAPI-template routing table. **The traefik-authproxy's
+live-discovery path fetches only `auth-policy.cedar`** (not the JSON document)
+and rebuilds its routing table from those annotations
+(`policy_store.parse_cedar_document`), then evaluates it for the
+authorization decision according to `CEDAR_MODE`. `auth-policy.json` is still
+served and still on the classpath — it remains the routing source for the
+**signed-bundle** policy path (`policy_bundle.py`, which packages
+`modules/<name>.json` today) — but a module integrating only for live
+discovery must serve `auth-policy.cedar` for the ACS to route to it at all.
+The `--module` name must equal the module's gateway path prefix (e.g.
+`payment-gateway`), because it is baked into the Cedar resource ids.
 
 The **Tier-2 domain** set (`auth-policy-domain.cedar`, from
 `--cedar-domain-output`) is **not** served over the well-known endpoint — it is
@@ -432,7 +441,7 @@ paths:
 
 ### Generated outputs
 
-**auth-policy.json**:
+**auth-policy.json** (signed-bundle routing source):
 ```json
 {
   "version": 1,
@@ -447,6 +456,21 @@ paths:
 }
 ```
 
+**auth-policy.cedar** (live-discovery routing + decision source — same fields, as annotations):
+```
+@id("auditflow::publishEvent")
+@path("/audit/publish")
+@method("POST")
+@public("false")
+@tenantRequired("true")
+@scopes("audit-event:write")
+permit(
+  principal,
+  action == Labs64IO::Action::"invoke",
+  resource == Labs64IO::ApiOperation::"auditflow::publishEvent"
+) when { (context has tenant) && (context.scopes.contains("audit-event:write")) };
+```
+
 **Generated AuditEventApi.java**:
 ```java
 @RequireTenant
@@ -486,3 +510,24 @@ Add your paths to `labs64.auth-context.public-paths` or ensure the gateway sends
 ### Annotations not enforced
 
 Ensure `auth-context-spring-boot-starter` is on the classpath and `labs64.auth-context.enabled` is not set to `false`.
+
+## Reading @Authorize enforcement logs
+
+Each `@Authorize` decision emits a non-sensitive summary on `io.labs64.authcontext.cedar.LoggingDecisionListener`:
+
+```
+cedar-domain outcome=<enforced|shadow>-<allow|deny> decision=<allow|deny|error> \
+  mode=<enforce|shadow> action=<a> resourceType=<t> reasons=<policyIds|-> requestId=<id>
+```
+
+INFO for a clean allow, WARN for deny/error.
+
+Sensitive fields (user, tenant, resolved resource id, raw error) ride the dedicated `io.labs64.authcontext.cedar.detail` logger at DEBUG, off by default. Enable it during the Cedar testing phase, e.g. in `application.yaml`:
+
+```yaml
+logging:
+  level:
+    io.labs64.authcontext.cedar.detail: DEBUG
+```
+
+The detail line emits `cedar-detail requestId=<id> user=<user> tenant=<tenant> resource=<type>::<id>[ error=<err>]`, shareable with the summary for joining via `requestId`.

auth-context-java/pom.xml

@@ -64,7 +64,7 @@
             <artifactId>jackson-dataformat-yaml</artifactId>
             <optional>true</optional>
         </dependency>
-        <!-- Cedar domain PEP (RFC-05 P3): optional — modules opt in by adding this
+        <!-- Cedar domain PEP: optional — modules opt in by adding this
              dependency themselves (uber classifier bundles the native FFI for
              linux/macos/windows, ~27 MB) plus labs64.auth.cedar.enabled=true.
              The cedar autoconfiguration is @ConditionalOnClass-guarded. -->

auth-context-java/src/main/java/io/labs64/authcontext/autoconfigure/AuthContextAutoConfiguration.java

@@ -6,9 +6,18 @@
 import org.springframework.boot.autoconfigure.condition.ConditionalOnResource;
 import org.springframework.boot.autoconfigure.condition.ConditionalOnWebApplication;
 import org.springframework.boot.context.properties.EnableConfigurationProperties;
+import java.io.BufferedReader;
+import java.io.IOException;
+import java.io.InputStreamReader;
+import java.io.UncheckedIOException;
+import java.nio.charset.StandardCharsets;
+import java.util.List;
+
 import org.springframework.boot.web.servlet.FilterRegistrationBean;
 import org.springframework.context.annotation.Bean;
 import org.springframework.core.Ordered;
+import org.springframework.core.io.Resource;
+import org.springframework.core.io.ResourceLoader;
 import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
 
 import io.labs64.authcontext.authorization.RequireScopesInterceptor;
@@ -20,6 +29,7 @@
 import io.labs64.authcontext.web.AuthContextProperties;
 import io.labs64.authcontext.web.AuthContextWebMvcConfigurer;
 import io.labs64.authcontext.web.AuthPolicyController;
+import io.labs64.authcontext.web.PublicPathMatcher;
 
 @AutoConfiguration
 @ConditionalOnWebApplication(type = ConditionalOnWebApplication.Type.SERVLET)
@@ -33,12 +43,31 @@ public AuthContextParser authContextParser() {
         return new AuthContextParser();
     }
 
+    @Bean
+    @ConditionalOnMissingBean
+    public PublicPathMatcher publicPathMatcher(AuthContextProperties properties, ResourceLoader resourceLoader) {
+        Resource resource = resourceLoader.getResource(properties.getPublicPathsLocation());
+        if (!resource.exists()) {
+            // No generated list (module has no public OpenAPI operations, or the
+            // build step is not wired): fall back to configured prefixes only.
+            return PublicPathMatcher.empty();
+        }
+        try (BufferedReader reader = new BufferedReader(
+                new InputStreamReader(resource.getInputStream(), StandardCharsets.UTF_8))) {
+            List<String> lines = reader.lines().toList();
+            return PublicPathMatcher.fromLines(lines);
+        } catch (IOException e) {
+            throw new UncheckedIOException(
+                    "Failed to read generated public paths from " + properties.getPublicPathsLocation(), e);
+        }
+    }
+
     @Bean
     @ConditionalOnMissingBean
     public FilterRegistrationBean<AuthContextFilter> authContextFilter(AuthContextProperties properties,
-            AuthContextParser parser) {
+            AuthContextParser parser, PublicPathMatcher publicPathMatcher) {
         FilterRegistrationBean<AuthContextFilter> registration = new FilterRegistrationBean<>(
-                new AuthContextFilter(properties, parser));
+                new AuthContextFilter(properties, parser, publicPathMatcher));
         registration.setOrder(Ordered.HIGHEST_PRECEDENCE + 10);
         return registration;
     }

auth-context-java/src/main/java/io/labs64/authcontext/cedar/AuthorizationDecision.java

@@ -6,8 +6,7 @@
 
 /**
  * One Cedar domain authorization decision — published to every
- * {@link AuthorizationDecisionListener} for auditability (RFC-05 P9/F9:
- * allow AND deny, with the matched policy ids, deterministic and replayable).
+ * {@link AuthorizationDecisionListener} for auditability.
  *
  * @param action       Cedar action id (unqualified)
  * @param resourceType Cedar resource type (unqualified)
@@ -30,4 +29,21 @@ public record AuthorizationDecision(String action, String resourceType, String r
     public AuthorizationDecision {
         reasons = reasons == null ? List.of() : List.copyOf(reasons);
     }
+
+    /** Three-valued decision for logs: {@code allow} / {@code deny} / {@code error}. */
+    public String decision() {
+        return error != null ? "error" : allowed ? "allow" : "deny";
+    }
+
+    /**
+     * Enforcement outcome verb: {@code enforced-allow} / {@code enforced-deny} /
+     * {@code shadow-allow} / {@code shadow-deny}. An errored decision is a deny
+     * (fail-closed), so its outcome carries the blocking action, while
+     * {@link #decision()} still reports {@code error} as the reason.
+     */
+    public String outcome() {
+        String phase = enforced ? "enforced" : "shadow";
+        String result = (allowed && error == null) ? "allow" : "deny";
+        return phase + "-" + result;
+    }
 }

auth-context-java/src/main/java/io/labs64/authcontext/cedar/Authorize.java

@@ -7,7 +7,7 @@
 import java.lang.annotation.Target;
 
 /**
- * Fine-grained Cedar domain authorization on a handler method (RFC-05 P3).
+ * Fine-grained Cedar domain authorization on a handler method.
  *
  * <p>Additive to the coarse {@code @RequireScopes}/{@code @RequireTenant}
  * pre-filters: those stay as fast gates, Cedar is the authoritative

auth-context-java/src/main/java/io/labs64/authcontext/cedar/AuthorizeInterceptor.java

@@ -22,7 +22,7 @@
 import jakarta.servlet.http.HttpServletResponse;
 
 /**
- * The {@code @Authorize} PEP (RFC-05 P3): runs after the coarse
+ * The {@code @Authorize} PEP: runs after the coarse
  * {@code @RequireTenant}/{@code @RequireScopes} pre-filters, resolves the
  * domain resource through the module's {@link CedarEntityResolver}, asks the
  * Cedar PDP, publishes the decision to every
@@ -65,10 +65,13 @@ public boolean preHandle(@NonNull final HttpServletRequest request,
             // The AuthContextFilter fails closed before us on protected paths;
             // this is defense in depth for misconfigured public paths.
             if (service.isEnforcing()) {
+                logger.warn("cedar-domain outcome=enforced-deny decision=deny mode=enforce "
+                        + "action={} reason=no-auth-context requestId=-", annotation.action());
                 response.sendError(HttpServletResponse.SC_UNAUTHORIZED);
                 return false;
             }
-            logger.warn("cedar-domain action={} skipped: no AuthContext (shadow)", annotation.action());
+            logger.warn("cedar-domain outcome=shadow-deny decision=deny mode=shadow "
+                    + "action={} reason=no-auth-context requestId=-", annotation.action());
             return true;
         }
 

auth-context-java/src/main/java/io/labs64/authcontext/cedar/CedarAuthorizationService.java

@@ -32,7 +32,7 @@
 import io.labs64.authcontext.core.AuthHeaders;
 
 /**
- * In-process Cedar domain PDP (RFC-05 P3, Tier 2).
+ * In-process Cedar domain PDP.
  *
  * <p>Loads the module's domain policy set once at startup and evaluates
  * {@code @Authorize} checks against it. Request construction follows the

auth-context-java/src/main/java/io/labs64/authcontext/cedar/CedarAutoConfiguration.java

@@ -16,11 +16,11 @@
 import com.cedarpolicy.BasicAuthorizationEngine;
 
 /**
- * Cedar domain PEP wiring (RFC-05 P3). Doubly opt-in: the module must add the
+ * Cedar domain PEP wiring. Doubly opt-in: the module must add the
  * optional {@code com.cedarpolicy:cedar-java} (uber) dependency AND set
  * {@code labs64.auth.cedar.enabled=true}. Registered after the coarse
  * interceptors so {@code @RequireScopes}/{@code @RequireTenant} stay the fast
- * pre-filter (RFC-05 §4.6).
+ * pre-filter.
  */
 @AutoConfiguration
 @ConditionalOnWebApplication(type = ConditionalOnWebApplication.Type.SERVLET)