Merge branch 'feat/rfc07-cerbos'

Author: r-brown

.github/workflows/labs64io-ci.yml

@@ -26,8 +26,12 @@ jobs:
           cache: maven
       - name: Test auth-context-java
         run: cd auth-context-java && mvn -B -ntp test
+      - name: Install auth-context-java (dependency for authz-queryplan-jpa)
+        run: cd auth-context-java && mvn -B -ntp -DskipTests install
       - name: Test openapi-spring-boot-starter
         run: cd openapi-spring-boot-starter && mvn -B -ntp test
+      - name: Test authz-queryplan-jpa
+        run: cd authz-queryplan-jpa && mvn -B -ntp test
 
   python:
     runs-on: ubuntu-latest
@@ -42,20 +46,12 @@ jobs:
           pip install -q -e ".[dev]"
           pytest -q
 
-  # 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:
+  # Generate the reference Cerbos policy set
+  # from the SAME x-labs64-auth (F3, no-drift) and run cerbos compile + the
+  # truth-table suite — including the cross-tenant isolation invariant (F4/F8).
+  cerbos:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: dtolnay/rust-toolchain@stable
-      - name: Cache cedar CLI
-        uses: actions/cache@v4
-        with:
-          path: ~/.cargo/bin
-          key: cedar-cli-4.11.2
-      - name: Install cedar CLI
-        run: command -v cedar || cargo install cedar-policy-cli --version 4.11.2 --locked
-      - name: Cedar schema + cross-tenant isolation gate
-        run: ./auth-policy-cedar/validate.sh
+      - name: Cerbos compile + decision-equivalence truth-table gate
+        run: ./auth-policy-cerbos/validate.sh

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. Includes: the auth-context libraries (Java + Python), which parse, enforce and propagate the trusted gateway header contract, shared Spring Boot starters, 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).
+Shared cross-service libraries for the Labs64.IO Ecosystem. Includes: the auth-context libraries (Java + Python), which parse, enforce and propagate the trusted gateway header contract, shared Spring Boot starters, plus the authorization assets: the engine-neutral `@Authorize` domain PEP in the Java starter (`io.labs64.authcontext.authorization`) with a Cerbos PDP client (`io.labs64.authcontext.cerbos`), feature-flagged via `labs64.auth.authz.*` (decisions delegated to the central Cerbos PDP over gRPC), the Cerbos-policy generator backend in `OpenApiAuthPreprocessor` (`--cerbos-output`/`--routes-output`), the decision-equivalence gate in `auth-policy-cerbos/`, and the `authz-queryplan-jpa` Data-PEP translator.
 
 ## Critical guardrails
 
@@ -14,16 +14,17 @@ Shared cross-service libraries for the Labs64.IO Ecosystem. Includes: the auth-c
 4. **No mandatory runtime dependencies in the Python package.** FastAPI/httpx integrations import lazily; the core must stay dependency-free.
 5. **Fail closed.** Non-public paths without a valid user identity return 401. Never weaken this default.
 6. **Value sanitization pattern `^[a-zA-Z0-9_.:-]+$`** must match the ACS (traefik-authproxy) exactly.
-7. **One Cedar schema.** `auth-policy-cedar/schema.cedarschema` is the single type system for BOTH authorization tiers (edge + every module's domain policies). Schema changes must keep `just cedar` green and stay in sync with `test-vectors/cedar-request-vectors.json` — the AuthContext→Cedar request contract the Java/Python PEPs are pinned to.
+7. **OpenAPI is the single source of policy.** Cerbos policies are GENERATED from each module's `x-labs64-auth` by `OpenApiAuthPreprocessor` — never hand-edit generated policy YAML. Decision equivalence (edge + domain, incl. the cross-tenant isolation invariant) is proven by `auth-policy-cerbos/validate.sh` (`just cerbos`); keep it green.
 
 ## Layout
 
 | Path | What |
 |---|---|
-| `auth-context-java/` | `io.labs64:auth-context-spring-boot-starter` |
+| `auth-context-java/` | `io.labs64:auth-context-spring-boot-starter` (auth-context + engine-neutral `@Authorize` PEP + Cerbos client) |
 | `auth-context-python/` | `auth-context-python` (package `auth_context`) |
-| `auth-policy-cedar/` | THE shared Cedar schema + reference policies + `validate.sh` CI gate |
-| `test-vectors/` | Canonical cross-language behavior vectors (headers + Cedar request construction) |
+| `authz-queryplan-jpa/` | `io.labs64:authz-queryplan-jpa` — Cerbos query-plan → JPA Specification (Data PEP) |
+| `auth-policy-cerbos/` | Reference OpenAPI → generated Cerbos policies + truth-table `validate.sh` CI gate |
+| `test-vectors/` | Canonical cross-language behavior vectors (header contract) |
 | `openapi-spring-boot-starter/` | `io.labs64:openapi-spring-boot-starter` |
 
 ## Commands
@@ -35,7 +36,7 @@ Shared cross-service libraries for the Labs64.IO Ecosystem. Includes: the auth-c
 | OpenAPI starter tests | `cd openapi-spring-boot-starter && mvn test` |
 | Python tests | `cd auth-context-python && .venv/bin/pytest` (after `just python-venv`) |
 | Install Java lib locally | `just install-java` |
-| Cedar schema/policy gate | `just cedar` (requires `cargo install cedar-policy-cli`) |
+| Cerbos policy + equivalence gate | `just cerbos` (runs `auth-policy-cerbos/validate.sh` via Docker) |
 
 ## Conventions
 

README.md

@@ -77,7 +77,7 @@ CLI:
 cd auth-context-java
 mvn -q exec:java \
   -Dexec.mainClass=io.labs64.authcontext.openapi.OpenApiAuthPreprocessorCli \
-  -Dexec.args="--input openapi.yaml --openapi-output target/generated/openapi.yaml --cedar-output target/generated/auth-policy.cedar --module commons"
+  -Dexec.args="--input openapi.yaml --openapi-output target/generated/openapi.yaml --cerbos-output target/cerbos --routes-output target/routes.yaml --module commons"
 ```
 
 ## Related

auth-context-java/INTEGRATION.md

@@ -10,14 +10,13 @@ The pipeline has four stages:
 OpenAPI spec (with x-labs64-auth)
   → OpenApiAuthPreprocessorCli (build-time)
     → Cleaned OpenAPI (annotations injected)
-    → auth-policy.cedar (gateway route policy)
+    → Cerbos resource policies (YAML) + routing manifest
   → openapi-generator (generates Java interfaces with annotations)
-  → auth-context-spring-boot-starter (runtime enforcement)
-  → GET /.well-known/auth-policy + /.well-known/auth-policy.cedar (runtime, served by the starter for the gateway ACS)
+  → auth-context-spring-boot-starter (runtime enforcement via @Authorize interceptors and central Cerbos PDP)
 ```
 
 1. **Author**: Add `x-labs64-auth` to each endpoint in your OpenAPI spec
-2. **Build-time**: The preprocessor strips the extension, injects Java annotations (`@RequireTenant`, `@RequireScopes`, `@PublicEndpoint`) into the generated OpenAPI, and emits `auth-policy.cedar`
+2. **Build-time**: The preprocessor strips the extension, injects Java annotations (`@RequireTenant`, `@RequireScopes`, `@PublicEndpoint`) into the generated OpenAPI, and emits Cerbos resource policies in YAML + routes manifest.
 3. **Code generation**: OpenAPI Generator produces Java API interfaces with the injected annotations
 4. **Runtime**: `auth-context-spring-boot-starter` auto-configures filters and interceptors that enforce the annotations
 
@@ -86,9 +85,9 @@ 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. This is
+module's `@Authorize` PEP against a typed Cerbos 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
+(`auth-policy-domain.cerbos`): the preprocessor emits one `permit` keyed on the
 operationId, conditioned on the same `tenant`/`scopes`, plus one structural
 cross-tenant guard per resource type. Operations without `resource` are
 edge-only (coarse reachability).
@@ -106,8 +105,8 @@ paths:
 ```
 
 The resource `<Type>` must be declared in the shared schema
-(`labs64.io-commons/auth-policy-cedar/schema.cedarschema`), and the module
-supplies the resource's `tenant` at request time via a `CedarEntityResolver`.
+(`labs64.io-commons/auth-policy-cerbos/schema.cerbosschema`), and the module
+supplies the resource's `tenant` at request time via a `CerbosEntityResolver`.
 Fine-grained resource-attribute rules (workflow status, ownership) are **not**
 expressible from OpenAPI — they stay in the service layer (and later Postgres
 RLS), by design.
@@ -131,14 +130,12 @@ Add three things to your `pom.xml`:
     <exec-maven-plugin.version>3.6.2</exec-maven-plugin.version>
     <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.cedar</auth-policy.generated>
-    <!-- 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)
-         domain → auth-policy-domain.cedar (Tier 2, module @Authorize PEP) -->
-    <auth-policy-cedar.generated>${project.build.directory}/generated-resources/auth-policy.cedar</auth-policy-cedar.generated>
-    <auth-policy-cedar-domain.generated>${project.build.directory}/generated-resources/auth-policy-domain.cedar</auth-policy-cedar-domain.generated>
+    <!-- Cerbos policies + routes manifest generated from x-labs64-auth.
+         auth-policy.module must equal the module's gateway prefix
+         (= policy-sources.yaml name); it is baked into the Cerbos resource
+         kind (your-module -> your_module_api). Generated output is a build
+         artifact only — the central Cerbos PDP owns the live policy set. -->
+    <auth-policy-cerbos.output>${project.build.directory}/cerbos</auth-policy-cerbos.output>
     <auth-policy.module>your-module</auth-policy.module>
 </properties>
 ```
@@ -187,10 +184,8 @@ The preprocessor must run **before** the OpenAPI generator. Add `exec-maven-plug
                             <argument>${openapi.source}</argument>
                             <argument>--openapi-output</argument>
                             <argument>${openapi.generated}</argument>
-                            <argument>--cedar-output</argument>
-                            <argument>${auth-policy-cedar.generated}</argument>
-                            <argument>--cedar-domain-output</argument>
-                            <argument>${auth-policy-cedar-domain.generated}</argument>
+                            <argument>--cerbos-output</argument>
+                            <argument>${auth-policy-cerbos.output}</argument>
                             <argument>--module</argument>
                             <argument>${auth-policy.module}</argument>
                         </arguments>
@@ -231,7 +226,7 @@ The preprocessor must run **before** the OpenAPI generator. Add `exec-maven-plug
             </executions>
         </plugin>
 
-        <!-- 3. Build helper: add generated resources (auth-policy.cedar) to classpath -->
+        <!-- 3. Build helper: add generated resources to classpath -->
         <plugin>
             <groupId>org.codehaus.mojo</groupId>
             <artifactId>build-helper-maven-plugin</artifactId>
@@ -273,28 +268,23 @@ The preprocessor must run **before** the OpenAPI generator. Add `exec-maven-plug
 
 Run `mvn clean compile` and check three outputs:
 
-### 1. Generated auth-policy.cedar
+### 1. Generated Cerbos output
 
 ```bash
-cat target/generated-resources/auth-policy.cedar
+ls target/cerbos
+# Should contain routes.yaml and Cerbos resource policies (e.g., your_module_api.yaml)
+cat target/cerbos/routes.yaml
 ```
 
 Should contain route entries for each endpoint:
 
-```json
-{
-  "version": 1,
-  "routes": [
-    {
-      "operationId": "publishEvent",
-      "method": "POST",
-      "path": "/audit/publish",
-      "public": false,
-      "tenantRequired": true,
-      "scopes": ["audit-event:write"]
-    }
-  ]
-}
+```yaml
+routes:
+  /audit/publish:
+    POST:
+      module: auditflow
+      operationId: publishEvent
+      public: false
 ```
 
 ### 2. Generated OpenAPI with annotations
@@ -347,48 +337,16 @@ labs64:
 
 4. **`@PublicEndpoint`**: Bypasses both interceptors. The path must also be in `labs64.auth-context.public-paths` to pass the filter.
 
-## The `/.well-known/auth-policy` endpoints
-
-When `auth-policy.cedar` is on the classpath (Step 2c's `add-resource`), the
-starter auto-registers a controller serving it verbatim at
-`GET /.well-known/auth-policy`. The gateway's traefik-authproxy discovers
-modules via the `labs64.io/auth-policy=true` Service label and fetches this
-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). Each generated permit
-also carries `@path`/`@method`/`@public`/`@tenantRequired`/`@scopes`
-annotations — the same fields `auth-policy.cedar`'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.cedar` 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
-consumed only in-process by this module's `@Authorize` PEP from the classpath
-(`labs64.auth.cedar.policy-location`, default `classpath:auth-policy-domain.cedar`).
-Both files are generated from the one `x-labs64-auth` source, so traefik and the
-module enforce the same OpenAPI-derived contract.
-
-- Both paths are **unconditionally public** in `AuthContextFilter` — they
-  cannot be disabled via `public-paths`, because the ACS must reach them
-  before it can authorize anything.
-- It is **not** exposed through the external gateway: module IngressRoutes
-  only publish API prefixes. The policy content is derived from the OpenAPI
-  spec (whose `/v3/api-docs` is public), so no secrets are involved.
-- Scope matching at the edge and in `RequireScopesInterceptor` is **OR**
-  (any listed scope suffices). The edge tenant check is presence-only —
-  tenant validation stays a module concern via `AuthContext.tenantId()`.
+## Policy Distribution to the Central PDP
+
+Services **no longer serve** authorization policies at runtime (the `/.well-known/auth-policy` endpoints have been deleted). Instead, the generated Cerbos policies and route manifests are collected from the build artifacts (`target/cerbos`) and distributed to the Central PDP via a GitOps CI pipeline. 
+
+1. **Build Time**: The OpenAPI preprocessor emits Cerbos YAML policies (`<module>_api.yaml` and `<DomainResource>.yaml`) and a `routes.yaml` manifest.
+2. **CI Pipeline**: A shared script (`build-cerbos-policies.sh`) aggregates the `target/cerbos` directories from all modules into a centralized policy distribution format.
+3. **Runtime**: The central Cerbos PDP loads these generated policies from a mounted ConfigMap. The Traefik Authproxy loads the `routes.yaml` manifests to understand the path-to-operation mappings.
+4. **Enforcement**: When a request arrives, the Traefik Authproxy queries the central Cerbos PDP for edge reachability (Tier 1). Then, inside your module, the `@Authorize` interceptors from `auth-context-spring-boot-starter` query the central Cerbos PDP for fine-grained domain authorization (Tier 2).
+
+This disconnected topology guarantees zero engine footprint inside the Java application, as the policy engine evaluates entirely out-of-process.
 
 ### Accessing the auth context in controllers
 
@@ -439,34 +397,22 @@ paths:
 
 ### Generated outputs
 
-**auth-policy.cedar** (signed-bundle routing source):
-```json
-{
-  "version": 1,
-  "routes": [{
-    "operationId": "publishEvent",
-    "method": "POST",
-    "path": "/audit/publish",
-    "public": false,
-    "tenantRequired": true,
-    "scopes": ["audit-event:write"]
-  }]
-}
-```
-
-**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 Cerbos edge policy (`target/cerbos/auditflow_api.yaml`)**:
+```yaml
+apiVersion: api.cerbos.dev/v1
+resourcePolicy:
+  version: default
+  resource: auditflow_api
+  rules:
+    - actions: ["publishEvent"]
+      effect: EFFECT_ALLOW
+      roles: ["*"]
+      condition:
+        match:
+          all:
+            of:
+              - expr: has(request.principal.attr.tenant)
+              - expr: '"audit-event:write" in request.principal.attr.scopes'
 ```
 
 **Generated AuditEventApi.java**:
@@ -511,21 +457,21 @@ Ensure `auth-context-spring-boot-starter` is on the classpath and `labs64.auth-c
 
 ## Reading @Authorize enforcement logs
 
-Each `@Authorize` decision emits a non-sensitive summary on `io.labs64.authcontext.cedar.LoggingDecisionListener`:
+Each `@Authorize` decision emits a non-sensitive summary on `io.labs64.authcontext.cerbos.LoggingDecisionListener`:
 
 ```
-cedar-domain outcome=<enforced|shadow>-<allow|deny> decision=<allow|deny|error> \
+cerbos-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`:
+Sensitive fields (user, tenant, resolved resource id, raw error) ride the dedicated `io.labs64.authcontext.cerbos.detail` logger at DEBUG, off by default. Enable it during the Cerbos testing phase, e.g. in `application.yaml`:
 
 ```yaml
 logging:
   level:
-    io.labs64.authcontext.cedar.detail: DEBUG
+    io.labs64.authcontext.cerbos.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`.
+The detail line emits `cerbos-detail requestId=<id> user=<user> tenant=<tenant> resource=<type>::<id>[ error=<err>]`, shareable with the summary for joining via `requestId`.