# aere-cloud (Java)

The official Java client for the [Aere Cloud API](https://aere.network/cloud.html) — one keyed
endpoint for RPC, post-quantum signature verification, chain data, notarization, webhooks and
gas sponsorship on Aere Network (chain 2800). **Zero dependencies** beyond the standard library:
`java.net.HttpURLConnection` and `javax.crypto` only. Since 1.6.1 the class uses only the Java 8 API (the tests enforce it with
`javac --release 8`), which is what Android provides; it has not yet been run on an Android device (see below). It does not follow redirects: a 3xx is raised as an
error, so your API key is never sent to a host you did not name.

Mirror of `@aere/cloud` (JS) and `aere-cloud` (Python): same routes, same semantics. Bodies are
raw JSON strings — the client does not force a JSON library on the integrator; parse responses
with whatever you already use (Jackson, Gson, `org.json`, ...).

## Use

```java
import network.aere.cloud.AereCloud;

var aere = new AereCloud(System.getenv("AERE_KEY"));

String head = aere.dataHead();          // {"block":...,"chainId":2800,...}
String anchors = aere.anchors(5);       // post-quantum anchor certificates
long n = aere.blockNumber();

// a smart account with a POST-QUANTUM owner (Falcon-512), gas sponsored:
String acct = aere.sponsorCreatePqAccount("0x09" + falconPkHex, 0);

// Trust API (1.6.0): any AERE Proof Protocol (AIP-23) envelope (JSON text) -> VALID / INVALID / PARTIAL with the levels checked
String verdict = aere.verify(envelopeJson, 2800);

// identity and compliance (1.7.0): the request as JSON text, sent as given; read "verdict" (PARTIAL: some rows not judged)
String id = aere.identityVerify("{\"presentation\":" + presentationJson + ",\"audience\":\"https://your.app/verifier\",\"nonce\":\"" + nonce + "\"}");
String ok = aere.complianceCheck(requestWithPolicyJson);

// verify a webhook delivery (constant-time HMAC) — never trust one without this:
boolean ok = AereCloud.verifyWebhook(rawBodyBytes, request.header("x-aere-signature"), secret);
```

Non-2xx responses raise `AereCloud.AereCloudException` with `.status`, `.body` (server JSON)
and `.path`.

## Since 1.5.0 (same surface as the JS and Python SDKs 1.5.0)

```java
aere.proof("0x" + sha256Hex);                            // a proof with its post-quantum finality
aere.readiness("example.com", false, false);             // quantum-readiness scan, free, no key sent
aere.readinessPerimeter("example.com", new String[]{"api"}, null, false); // a domain's whole public perimeter
aere.pqFinality("latest", "testnet", "both");         // AIP-21 per-block PQ finality, both clients

AereCloud.AuditExport day = aere.auditExport("2026-09-24", "jsonl");
// day.bytes are the exact bytes of the day file; day.verified is true only if THEIR sha256 equals the stated digest

aere.auditRetention();                                    // read-only with the API key; set it in the console
AereCloud.KeptCheck k = aere.auditVerifyKept("2026-05-01", keptBytes);
// k.matches: your kept export still matches the day we hold, or the tombstone (digest) a deleted day left behind
```

`auditVerifyKept` hashes YOUR bytes locally. An error (rate limit, network) is raised, never returned as "does not match".

## Android

Copy `src/main/java/network/aere/cloud/AereCloud.java` into your app module (package `network.aere.cloud`) and call it off the main
thread, as with any network call on Android. What is measured: the class compiles against the Java 8 API (`javac --release 8`) and its
tests pass on the JDK. What is not: we have not run it on an Android device or emulator.

## Tests

```
javac --release 8 -d out8 src/main/java/network/aere/cloud/AereCloud.java          # the Android gate: Java 8 API only
javac -d out src/main/java/network/aere/cloud/AereCloud.java src/test/java/network/aere/cloud/TestAereCloud.java
java -cp out network.aere.cloud.TestAereCloud                    # unit, offline
AERE_KEY=ak2800... java -cp out network.aere.cloud.TestAereCloud --live   # + live probes
```

Measured 2026-08-27: 7/7 green, including live probes against production (health, validator
set, block number, and the free JSON refusal on the PQ sponsorship route).

Measured 2026-09-28 (1.6.1, JDK 21): 9/9 offline, including a 302 to a second local host that receives zero requests; the negative
control (`node control-negativ.mjs`) turns 8 of 8 planted faults red, among them a followed redirect and two post-Java-8 calls that
the JDK tests alone would not catch but `--release 8` refuses.

Measured 2026-09-25 (1.5.0): 7/7 offline, the new routes judged against a local JDK HTTP server (what the client sends,
what it does with each answer). `node control-negativ.mjs` breaks five guards in a copy of the class and requires each
one's test to fail: 5/5 red, the untouched class green.