Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 15 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

## [Unreleased]

The first Java SDK release carrying these entries sends the PEP capability handshake, which a
platform reads from v10.4.0, and reaches /api/v1/typed-policies, which needs a v11.0.0 platform;
against an older platform it works unchanged. Upgrade the SDK before the platform: from v11.0.0,
Decide under an organization's redact override refuses a caller that does not declare redaction,
and only a release that sends the handshake can declare it.

### Added

- **v11.0.0 decision provenance on every governed response (axonflow-enterprise#3746).**
Expand All @@ -31,7 +37,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
reported once, as its template (`GET /api/v1/static-policies/{id}`), not once per id. From
v11.0.0 the legacy policy routes carry it: the static- and dynamic-policy routes and the policy
simulation routes.
- **The v11.0.0 PEP capability handshake (axonflow-enterprise#3746).** An enforcement point
- **The PEP capability handshake, which a platform reads from v10.4.0
(axonflow-enterprise#3746).** An enforcement point
declares the obligation types and schema versions it can discharge with `PEPHandshake.of(...)`
and `PEPCapability.of(...)`, presented as `X-Axonflow-PEP-Handshake` on every call to a plane
that reads it: `decide` (and `decideAndFulfill` and `fulfillRequest`'s engine round-trip),
Expand All @@ -50,6 +57,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
`Retry-After`; `active()` is empty when nothing is active. A client derived with `asUser` has
its own namespace. Rolling back and withdrawing are customer portal operations the agent does
not proxy, so the SDK has no method for either.
- **Two runnable examples for the v11 platform (axonflow-enterprise#3746).** `examples/pep-handshake` declares an enforcement
point's capabilities and decides with them, printing each verdict and its reasons;
`examples/typed-policies` reads what the deployment may author, validates a document and, with
`AXONFLOW_TYPED_POLICY_PUBLISH=1`, publishes and activates it. Run the handshake example first:
after a document with an organization-scope constraint is activated, a decide that does not
supply the attribute the constraint conditions on is denied fail-closed with reasons
`["unknown_constraint"]`.

### Deprecated

Expand Down
29 changes: 25 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -366,9 +366,9 @@ This surface does **not** go through the client's `RetryConfig`. That executor i

The rest of the package is hand-written and is meant to be edited: `Attribute`, `AttributeValue`, `AttributeMap`, `AuthZENDecision`, `AuthZENEvaluation`, `AuthZENRefusals`, and the six exception types (`AuthZENEvaluationException` and its five subclasses).

### PEP capability handshake
### PEP capability handshake (v10.4.0+)

A v11 platform lets an enforcement point declare, on each call, the exact obligation types and schema versions it can discharge. Build the declaration once and give it to the client:
A platform from v10.4.0 lets an enforcement point declare, on each call, the exact obligation types and schema versions it can discharge. Build the declaration once and give it to the client:

```java
PEPHandshake declared =
Expand All @@ -393,10 +393,24 @@ The client sends it on every call to a plane that reads it: `decide`, the engine

One process can be two enforcement points: a request path and a response path that discharge different obligations. `client.withPEPHandshake(other)` derives a client presenting `other` in place of the client's declaration. Like `asUser`, it shares the parent's connection pool, so never close a derived client.

- **There is no default.** A client given no declaration sends no header, and the platform behaves as it did before the handshake existed. `List.of()` declares that the enforcement point discharges nothing; a null list is refused.
- **There is no default.** A client given no declaration sends no header. From v11.0.0 an absent declaration has a consequence: on both editions, a decide under an organization's redact override refuses a caller that does not declare redaction, so declare what your enforcement point discharges. `List.of()` declares that the enforcement point discharges nothing; a null list is refused.
- **What a declaration changes.** On an Enterprise deployment, an allow verdict carrying a mandatory obligation the declared set cannot discharge becomes a deny, so declare every obligation your enforcement point carries out, and only those. A Community deployment records the declaration without denying on it, and drops any capability in a family it does not issue.
- **Refused before it is sent.** `PEPHandshake.of` and `PEPCapability.of` apply the platform's own rules and throw `PEPHandshakeException` naming the member at fault (`getPointer()` is `/pep_id`, `/audience` or `/capabilities`), instead of the first governed call coming back `400`. A `PEPHandshake` is immutable and computes its header once, so every request carries exactly the value that was validated.

## The v11.0.0 platform

What each part of this SDK needs from the platform:

| Chapter | Platform minimum |
|---|---|
| [PEP capability handshake](#pep-capability-handshake-v1040) (`pepHandshake`, `withPEPHandshake`) | v10.4.0: every plane that reads the header records it; an older platform ignores it |
| [Typed policy authoring](#typed-policy-authoring-v1100) (`typedPolicies()`) | v11.0.0 |
| Decision provenance (`getEngine()`, `getSubjectType()`, `getPolicyBundle()`, `getPolicyIdentities()` and the rest) | v11.0.0; against an older platform they read null or empty |
| Route deprecation reports (`onRouteDeprecation`) | v11.0.0 stamps the legacy policy routes |
| The legacy policy write freeze (`LegacyPolicyWriteFrozenException`) | v11.0.0 |

Upgrade the SDK before the platform: from v11.0.0, a decide under an organization's redact override refuses a caller that does not declare redaction, and only a release that sends the handshake can declare it. Against an older platform the SDK works unchanged.

## Typed policy authoring (v11.0.0+)

A v11 platform authors policy as a typed document: validated, published as a signed artifact pinned by its digest, and promoted to active. `client.typedPolicies()` reaches the six routes the agent proxies under `/api/v1/typed-policies`:
Expand All @@ -415,6 +429,7 @@ TypedPolicySystemCorpus system = typed.system(); // the platform's own controls
- **The organization and the author are the ones your credentials resolve to.** The agent stamps both, and the platform overwrites any author named inside the document. A client derived with `asUser` has its own namespace, and its user token is the caller.
- **Refusals are typed.** Every refusal is a `TypedPolicyRefusalException` with the HTTP status, the platform's reason (such as `publication_refused`, `activation_refused` or `tier_limit`), any findings, and `getRetryAfter()` when the refusal is retryable; a 401 is the client's `AuthenticationException`. On an edition with separation of duties, publishing refuses with the finding code `APPROVER_IS_AUTHOR`: the route names no approver, and such a deployment approves in the customer portal.
- **The document is the authoring model itself,** a `Map<String, Object>` rather than Java types, so a field the policy vocabulary gains is authorable without an SDK release. A null fixtures list sends none; an empty one sends `[]`. `validate` answers identically on every edition; the edition's boundary is applied when you publish.
- **System controls are changed in the document, not per policy.** A v11.0.0 platform retires per-policy overrides: `createPolicyOverride` and `deletePolicyOverride` answer 409 `LEGACY_POLICY_WRITE_FROZEN` (agent-api's `PerPolicyOverrideRetired` response), and a system control is enabled, disabled or re-actioned in the organization's typed document, in its `system_controls` section.

## v11.0.0 deprecations

Expand Down Expand Up @@ -725,11 +740,17 @@ Complete working examples for all features are available in the [examples folder
Runnable in this repository, against a live agent:

```bash
mvn -q -DskipTests install # put the SDK on the local classpath
mvn -q -DskipTests -DskipUnitTests=true install # put the SDK on the local classpath
AXONFLOW_AGENT_URL=http://localhost:8080 \
mvn -q -f examples/authzen/pom.xml compile exec:java # AuthZEN: 9 steps, 4 of them refusals
AXONFLOW_AGENT_URL=http://localhost:8080 \
mvn -q -f examples/pep-handshake/pom.xml compile exec:java # the PEP capability handshake
AXONFLOW_AGENT_URL=http://localhost:8080 AXONFLOW_TYPED_POLICY_PUBLISH=1 \
mvn -q -f examples/typed-policies/pom.xml compile exec:java # validate, publish, activate
```

Run `pep-handshake` before `typed-policies`. After a document with an organization-scope constraint is activated, a decide that does not supply the attribute the constraint conditions on is denied fail-closed with reasons ["unknown_constraint"]; supply the attribute or run the example on a fresh stack. On Enterprise the client id is the organization id and the secret its license key; a Community deployment accepts any credentials.

### Community Features

```java
Expand Down
43 changes: 43 additions & 0 deletions examples/pep-handshake/pom.xml
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0">
<modelVersion>4.0.0</modelVersion>

<groupId>com.getaxonflow.examples</groupId>
<artifactId>pep-handshake</artifactId>
<version>1.0-SNAPSHOT</version>
<packaging>jar</packaging>

<name>AxonFlow Java SDK — PEP Capability Handshake Example</name>
<description>
Declares an enforcement point's capabilities with the PEP capability handshake and
decides with it against a running AxonFlow agent. Run mvn install on the SDK first to
put the local artifact on the classpath.
</description>

<properties>
<!-- release, not source/target: pins the API surface to 11 on every JDK. -->
<maven.compiler.release>11</maven.compiler.release>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>

<dependencies>
<dependency>
<groupId>com.getaxonflow</groupId>
<artifactId>axonflow-sdk</artifactId>
<version>9.3.0</version>
</dependency>
</dependencies>

<build>
<plugins>
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>exec-maven-plugin</artifactId>
<version>3.1.0</version>
<configuration>
<mainClass>com.getaxonflow.examples.PepHandshake</mainClass>
</configuration>
</plugin>
</plugins>
</build>
</project>
Original file line number Diff line number Diff line change
@@ -0,0 +1,135 @@
// Copyright 2026 AxonFlow
// SPDX-License-Identifier: MIT
package com.getaxonflow.examples;

import com.getaxonflow.sdk.AxonFlow;
import com.getaxonflow.sdk.AxonFlowConfig;
import com.getaxonflow.sdk.authzen.AuthZENObligationType;
import com.getaxonflow.sdk.exceptions.PEPHandshakeException;
import com.getaxonflow.sdk.types.DecideRequest;
import com.getaxonflow.sdk.types.DecideResponse;
import com.getaxonflow.sdk.types.DecisionTarget;
import com.getaxonflow.sdk.types.PEPCapability;
import com.getaxonflow.sdk.types.PEPHandshake;
import java.util.List;

/**
* Declaring an enforcement point's capabilities with the PEP capability handshake, which the
* platform reads from v10.4.0.
*
* <p>An enforcement point (a PEP) declares, on each governed call, the exact obligation types and
* schema versions it can discharge. On an Enterprise deployment an allow verdict carrying a
* mandatory obligation the declared set cannot discharge becomes a deny, so the enforcement point
* is never handed an instruction it would drop; a Community deployment records the declaration.
* From v11.0.0, on both editions, a decide under an organization's redact override refuses a caller
* that does not declare redaction.
*
* <p>This example builds a declaration once for the client, derives a client presenting another one
* (one process can be two enforcement points), and shows that a declaration the platform would
* refuse fails here, before anything is sent. Each decide prints its verdict and reasons.
*
* <p>After a document with an organization-scope constraint is activated, a decide that does not
* supply the attribute the constraint conditions on is denied fail-closed with reasons
* ["unknown_constraint"]; supply the attribute or run this example on a fresh stack. Run it before
* the typed-policies example, which publishes and activates such a document.
*
* <p>On Enterprise the client id is the organization id and the secret its license key; a Community
* deployment accepts any credentials.
*
* <pre>
* mvn -q -DskipTests -DskipUnitTests=true install # from the repository root: the SDK on the local classpath
* AXONFLOW_AGENT_URL=http://localhost:8080 mvn -q -f examples/pep-handshake/pom.xml compile exec:java
* </pre>
*
* <p>Exits non-zero if a step fails, so it is usable as a smoke test.
*/
public final class PepHandshake {

private static int failures;

private PepHandshake() {}

@FunctionalInterface
private interface Step {
void run() throws Exception;
}

private static void step(String name, Step body) {
System.out.println("\n=== " + name + " ===");
try {
body.run();
System.out.println("ok");
} catch (Exception e) {
System.out.println("FAILED: " + e.getClass().getSimpleName() + ": " + e.getMessage());
failures++;
}
}

private static void print(DecideResponse decision) {
System.out.println(
"verdict="
+ decision.getVerdict()
+ " reasons="
+ decision.getReasons()
+ " obligations="
+ (decision.getObligations() == null ? 0 : decision.getObligations().size()));
}

public static void main(String[] args) {
String endpoint = System.getenv().getOrDefault("AXONFLOW_AGENT_URL", "http://localhost:8080");
String clientId = System.getenv("AXONFLOW_CLIENT_ID");
String clientSecret = System.getenv("AXONFLOW_CLIENT_SECRET");

// The request path redacts fields; it declares exactly that.
PEPHandshake requestPath =
PEPHandshake.of(
"checkout-gateway",
"https://pep.example.com",
List.of(PEPCapability.of(AuthZENObligationType.FIELD_REDACT, 1)));
AxonFlowConfig.Builder config =
AxonFlowConfig.builder().endpoint(endpoint).pepHandshake(requestPath);
if (clientId != null && !clientId.isEmpty()) {
config.clientId(clientId).clientSecret(clientSecret);
}
try (AxonFlow client = AxonFlow.create(config.build())) {
DecideRequest decide =
DecideRequest.builder("tool", "look up the weather")
.target(new DecisionTarget("tool", null, null, "search"))
.build();

step("decide with the client's declaration", () -> print(client.decide(decide)));

// The response path masks fields instead. A derived client presents its own declaration in
// place of the client's, and shares the client's connection pool: never close it.
step(
"decide with a derived client's declaration",
() -> {
PEPHandshake responsePath =
PEPHandshake.of(
"checkout-gateway-response",
"https://pep.example.com",
List.of(PEPCapability.of(AuthZENObligationType.FIELD_MASK, 1)));
print(client.withPEPHandshake(responsePath).decide(decide));
});

// A declaration the platform would refuse fails at construction, naming the member at fault,
// instead of the first governed call answering 400.
step(
"a declaration the platform would refuse",
() -> {
try {
PEPHandshake.of("Checkout:Gateway", "https://pep.example.com", List.of());
throw new IllegalStateException("the declaration was accepted");
} catch (PEPHandshakeException refusal) {
System.out.println(
"refused at " + refusal.getPointer() + ": " + refusal.getMessage());
}
});
}

if (failures > 0) {
System.out.println("\n" + failures + " step(s) failed");
System.exit(1);
}
}
}
43 changes: 43 additions & 0 deletions examples/typed-policies/pom.xml
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0">
<modelVersion>4.0.0</modelVersion>

<groupId>com.getaxonflow.examples</groupId>
<artifactId>typed-policies</artifactId>
<version>1.0-SNAPSHOT</version>
<packaging>jar</packaging>

<name>AxonFlow Java SDK — Typed Policy Authoring Example</name>
<description>
Typed policy authoring against a running AxonFlow v11 platform: what the deployment may
author, validate, optionally publish and activate, and the document in force. Run mvn
install on the SDK first to put the local artifact on the classpath.
</description>

<properties>
<!-- release, not source/target: pins the API surface to 11 on every JDK. -->
<maven.compiler.release>11</maven.compiler.release>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>

<dependencies>
<dependency>
<groupId>com.getaxonflow</groupId>
<artifactId>axonflow-sdk</artifactId>
<version>9.3.0</version>
</dependency>
</dependencies>

<build>
<plugins>
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>exec-maven-plugin</artifactId>
<version>3.1.0</version>
<configuration>
<mainClass>com.getaxonflow.examples.TypedPolicies</mainClass>
</configuration>
</plugin>
</plugins>
</build>
</project>
Loading
Loading