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
28 changes: 21 additions & 7 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,17 +53,31 @@ and only a release that sends the handshake can declare it.
to active. `client.typedPolicies()` reaches the six routes the agent proxies under
`/api/v1/typed-policies`: `edition()`, `validate(document, fixtures)`, `publish(document,
fixtures)`, `activate(digest, reason)`, `active()` and `system()`. Every refusal except a 401 is
a `TypedPolicyRefusalException` carrying the status, the platform's reason, any findings and
`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
a `TypedPolicyRefusalException` carrying the status, the platform's reason, any findings, the
policy a tier refusal names (`getPolicy()`) and `Retry-After`. `active()` is empty only for the
platform's `404 nothing_active`; any other 404 is a `TypedPolicyRefusalException` with status
404, and a v11.0.0 platform answers a document store it cannot read with 503
`storage_unavailable`, which throws it too (getaxonflow/axonflow-enterprise#4255). The answers
carry the edition's vocabulary (`getCatalogDigest()`, `getRegistryVersion()`,
`getCatalogFixture()`), the organization template controls a publication or an activation omits
(`getTemplateOmissions()`, a `TemplateOmissionReport`, or `getTemplateOmissionsUnavailable()`
when the platform could not report them), and each system control's `getName()`.
`TypedPolicySystemControl.getMandatory()` is a plain `boolean`, false when the platform omits
it. 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"]`.
`AXONFLOW_TYPED_POLICY_PUBLISH=1`, publishes and activates it, printing the publication's
template-omission report before it activates: activating a document that omits the
organization template's controls removes them for the organization. It finds its default
document on its classpath, so it runs from any directory, and it exits non-zero when a
publication or activation it asked for is refused. 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"]`. From v11.0.0 the deny's first reason is that code, followed by one
naming each constraint it could not evaluate and the attribute it needed
(getaxonflow/axonflow-enterprise#4247).

### Deprecated

Expand Down
12 changes: 7 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -426,8 +426,10 @@ TypedPolicySystemCorpus system = typed.system(); // the platform's own controls
```

- **Activation promotes.** A digest whose version does not advance past the active one is refused. Rolling back to an earlier document, and withdrawing the active one, are operations of the customer portal behind its session; the agent does not proxy them, so the SDK has no method for either.
- **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.
- **Activation replaces the organization template.** Activating a document that omits the organization template's controls removes those controls for the organization. The template's controls carry the destructive-command blocks, DROP and TRUNCATE prevention and the blocking SQL-injection rows. `publish()` and `activate()` report which ones a document omits as `getTemplateOmissions()`, and the example prints that report. The publish fixture the example uses is a minimal example, not a starting point for production: it omits all of them.
- **The agent stamps the organization and the author.** The platform signs the caller as author whatever the document names. The organization is the one your credentials resolve to; on Community it is the deployment's (`ORG_ID`). 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, `getPolicy()` for the policy a tier refusal names, 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.
- **`active()` is empty only for the platform's `nothing_active`.** Any other 404, from a platform before v11.0.0 or an endpoint that is not an agent, throws `TypedPolicyRefusalException` with status 404. A v11.0.0 platform answers a document store it cannot read with 503 `storage_unavailable`, which throws `TypedPolicyRefusalException` too (getaxonflow/axonflow-enterprise#4255).
- **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.

Expand Down Expand Up @@ -741,15 +743,15 @@ Runnable in this repository, against a live agent:

```bash
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
AXONFLOW_AGENT_URL=http://localhost:8080 \
mvn -q -f examples/authzen/pom.xml compile exec:java # AuthZEN: 9 steps, 4 of them refusals
```

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.
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. From v11.0.0 the deny's first reason is that code, followed by one naming each constraint it could not evaluate and the attribute it needed (getaxonflow/axonflow-enterprise#4247). On Enterprise the client id is the organization id and the secret its license key; a Community deployment accepts any credentials.

### Community Features

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -18,20 +18,22 @@
* 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.
* schema versions it can discharge. From v11.0.0, on every edition, the engine refuses a mandatory
* obligation the declaration cannot discharge: an organization's redact override on a decide
* refuses a caller that does not declare redaction. On an Enterprise deployment, in addition, an
* allow verdict carrying a mandatory obligation outside the declared set becomes a deny, so the
* enforcement point is never handed an instruction it would drop.
*
* <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.
* ["unknown_constraint"]; supply the attribute or run this example on a fresh stack. From v11.0.0
* the deny's first reason is that code, followed by one naming each constraint it could not
* evaluate and the attribute it needed (getaxonflow/axonflow-enterprise#4247). 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.
Expand Down
9 changes: 9 additions & 0 deletions examples/typed-policies/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,15 @@
</dependencies>

<build>
<resources>
<!-- The default document, on the classpath, so the example runs from any directory. -->
<resource>
<directory>../../tests/fixtures</directory>
<includes>
<include>typed_policy_publish_body.json</include>
</includes>
</resource>
</resources>
<plugins>
<plugin>
<groupId>org.codehaus.mojo</groupId>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -9,9 +9,12 @@
import com.getaxonflow.sdk.exceptions.TypedPolicyRefusalException;
import com.getaxonflow.sdk.types.policies.TypedPolicyTypes.ActiveTypedPolicy;
import com.getaxonflow.sdk.types.policies.TypedPolicyTypes.AuthoringFinding;
import com.getaxonflow.sdk.types.policies.TypedPolicyTypes.TemplateOmissionReport;
import com.getaxonflow.sdk.types.policies.TypedPolicyTypes.TypedAuthoringEdition;
import com.getaxonflow.sdk.types.policies.TypedPolicyTypes.TypedPolicyPublication;
import com.getaxonflow.sdk.types.policies.TypedPolicyTypes.TypedPolicyValidation;
import java.io.IOException;
import java.io.InputStream;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.List;
Expand All @@ -25,17 +28,26 @@
* pinned by its digest, and promoted to active. This example reads what the deployment may author,
* validates a document and prints every finding, and shows the document in force. It publishes and
* activates only when {@code AXONFLOW_TYPED_POLICY_PUBLISH=1}, because that changes the
* organization's active policy; a refusal prints the platform's reason and findings.
* organization's active policy.
*
* <p>Before it activates, it prints the publication's template-omission report: activating a
* document that omits the organization template's controls removes those controls for the
* organization. The default document is a minimal example, not a starting point for production:
* it omits all of them. A publication or activation that was asked for and refused prints the
* platform's reason and findings, and fails the run.
*
* <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. The default
* document is such a document, so run the pep-handshake example first.
* ["unknown_constraint"]; supply the attribute or run this example on a fresh stack. From v11.0.0
* the deny's first reason is that code, followed by one naming each constraint it could not
* evaluate and the attribute it needed (getaxonflow/axonflow-enterprise#4247). The default document
* is such a document, so run the pep-handshake example first.
*
* <p>{@code AXONFLOW_TYPED_POLICY_BODY} names a JSON file holding {@code {"document": ...,
* "fixtures": [...]}}; the default is {@code tests/fixtures/typed_policy_publish_body.json}, read
* from the directory Maven runs in. On an edition with separation of duties, see the README's Typed
* policy authoring section for how a publication is approved.
* "fixtures": [...]}}. Without it the example reads the repository's {@code
* tests/fixtures/typed_policy_publish_body.json}, which its build puts on the classpath, so it runs
* from any directory. On an edition with separation of duties, see the README's Typed policy
* authoring section for how a publication is approved.
*
* <pre>
* mvn -q -DskipTests -DskipUnitTests=true install # from the repository root: the SDK on the local classpath
Expand All @@ -47,6 +59,9 @@
*/
public final class TypedPolicies {

/** The default document, on the classpath. */
static final String DEFAULT_BODY = "/typed_policy_publish_body.json";

private static int failures;

private TypedPolicies() {}
Expand Down Expand Up @@ -84,17 +99,62 @@ private static void print(List<AuthoringFinding> findings) {
}
}

/** Prints a refusal: the platform's reason and any findings that refused it. */
private static void printRefusal(String what, TypedPolicyRefusalException refusal) {
System.out.println(
what
+ ": HTTP "
+ refusal.getStatus()
+ " "
+ refusal.getReason()
+ ": "
+ refusal.getMessage());
print(refusal.getFindings());
}

/**
* Prints which of the organization template's controls the document omits: activating it removes
* them for the organization.
*/
private static void printTemplateOmissions(TypedPolicyPublication published) {
TemplateOmissionReport report = published.getTemplateOmissions();
if (report != null) {
System.out.println(
"template omissions: "
+ report.getOmitted().size()
+ " of "
+ report.getOf()
+ " template controls: "
+ String.join(", ", report.getOmitted()));
} else if (published.getTemplateOmissionsUnavailable() != null) {
System.out.println(
"template omissions: unavailable: " + published.getTemplateOmissionsUnavailable());
} else {
System.out.println("template omissions: none");
}
}

/** The body {@code path} names, or the default document on the classpath when it is unset. */
static Map<String, Object> readBody(String path) throws IOException {
ObjectMapper mapper = new ObjectMapper();
TypeReference<Map<String, Object>> type = new TypeReference<Map<String, Object>>() {};
if (path != null && !path.isEmpty()) {
return mapper.readValue(Files.readAllBytes(Paths.get(path)), type);
}
try (InputStream in = TypedPolicies.class.getResourceAsStream(DEFAULT_BODY)) {
if (in == null) {
throw new IOException(
DEFAULT_BODY
+ " is not on the classpath: build the example with its pom, or set"
+ " AXONFLOW_TYPED_POLICY_BODY");
}
return mapper.readValue(in, type);
}
}

public static void main(String[] args) throws Exception {
String endpoint = System.getenv().getOrDefault("AXONFLOW_AGENT_URL", "http://localhost:8080");
String bodyPath =
System.getenv()
.getOrDefault(
"AXONFLOW_TYPED_POLICY_BODY", "tests/fixtures/typed_policy_publish_body.json");
Map<String, Object> body =
new ObjectMapper()
.readValue(
Files.readAllBytes(Paths.get(bodyPath)),
new TypeReference<Map<String, Object>>() {});
Map<String, Object> body = readBody(System.getenv("AXONFLOW_TYPED_POLICY_BODY"));
@SuppressWarnings("unchecked")
Map<String, Object> document = (Map<String, Object>) body.get("document");
@SuppressWarnings("unchecked")
Expand Down Expand Up @@ -137,29 +197,29 @@ public static void main(String[] args) throws Exception {
step(
"publish and activate",
() -> {
TypedPolicyPublication published;
try {
TypedPolicyPublication published = typed.publish(document, fixtures);
System.out.println(
"published "
+ published.getDigest()
+ " (version "
+ published.getVersion()
+ ")");
typed.activate(published.getDigest(), "examples/typed-policies");
System.out.println("activated");
published = typed.publish(document, fixtures);
} catch (TypedPolicyRefusalException refusal) {
// A refusal carries the platform's reason and, for a refused document, the findings
// that refused it.
System.out.println(
"refused: HTTP "
+ refusal.getStatus()
+ " "
+ refusal.getReason()
+ ": "
+ refusal.getMessage());
print(refusal.getFindings());
throw refusal; // publishing was asked for, so a refusal fails the step
// that refused it. Publishing was asked for, so a refusal fails the step.
printRefusal("refused", refusal);
throw refusal;
}
System.out.println(
"published " + published.getDigest() + " (version " + published.getVersion() + ")");
// Before activating: activating removes, for the organization, every template
// control the document omits.
printTemplateOmissions(published);
try {
typed.activate(published.getDigest(), "examples/typed-policies");
} catch (TypedPolicyRefusalException refusal) {
// Activation promotes: a document whose version does not advance past the active
// one is refused. Activating was asked for, so a refusal fails the step.
printRefusal("activation refused", refusal);
throw refusal;
}
System.out.println("activated");
});
}

Expand Down
Loading
Loading