0fe1828f5b
POST /v1/identity/verify: an AERE Identity presentation judged by the published command line -> VALID / PARTIAL / INVALID with every row, the claims shown and the subject when no row failed, and the command that reproduces the verdict. POST /v1/compliance/check: your policy judged on a presentation -> COMPLIANT / NOT_COMPLIANT with the reasons and, with record, the decision as an AIP-23 envelope without personal data. In Go the presentation, keys, lists and policy travel as json.RawMessage: a map or float64 would change numbers above 2^53 and the canonical text the signatures cover. The .NET negative control now builds clean for each planted defect (an incremental build could run the tests against the previous planted library). A negative control for the JavaScript and Python routes is added. Tests: JavaScript 13, Python 14, Go ok, Java 10/10 (and the Java 8 API gate); negative controls Go 9/9, Java 10/10, .NET 12/12, JavaScript and Python 4/4.
123 lines
6.8 KiB
Markdown
123 lines
6.8 KiB
Markdown
# @aere/cloud
|
|
|
|
The official 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; runs in Node 18+ and modern
|
|
browsers.
|
|
|
|
## Install
|
|
|
|
The clients are installed from this repository; they are not on the npm or PyPI registries yet, and a name there that
|
|
looks like ours is not ours.
|
|
|
|
```
|
|
npm install git+https://git.aere.network/aere-network/aere-cloud-sdk.git # JavaScript (@aere/cloud)
|
|
pip install "git+https://git.aere.network/aere-network/aere-cloud-sdk.git#subdirectory=python" # Python (aere-cloud)
|
|
go get git.aere.network/aere-network/aere-cloud-sdk/go@main # Go
|
|
```
|
|
|
|
Java: build `java/` from source with the JDK alone (see `java/README.md`); since 1.6.1 the same class is built against the Java 8 API, for Android too (not yet run on a device). .NET: build `csharp/Aere.Cloud` from source with the
|
|
.NET SDK (see `csharp/README.md`). All five clients have the same routes and semantics, and none of them follows redirects, so your
|
|
API key is never sent to a host you did not name.
|
|
|
|
Get a key: the free trial is self-serve at [aere.network/cloud.html#subscribe](https://aere.network/cloud.html#subscribe).
|
|
A key looks like `ak2800.<your-0x-address>.<secret>`.
|
|
|
|
## Use
|
|
|
|
```js
|
|
import { AereCloud } from '@aere/cloud';
|
|
|
|
const aere = new AereCloud({ apiKey: process.env.AERE_KEY });
|
|
|
|
// chain data
|
|
const head = await aere.dataHead();
|
|
const anchors = await aere.anchors(5); // post-quantum anchor certificates
|
|
const set = await aere.validators(); // live QBFT validator set
|
|
|
|
// JSON-RPC
|
|
const block = await aere.blockNumber();
|
|
|
|
// post-quantum verification, computed by the chain's own precompiles
|
|
const { valid } = await aere.pqVerify({
|
|
scheme: 'ml-dsa-44', publicKey: '0x…', signature: '0x…', message: '0x…',
|
|
});
|
|
|
|
// notarize a document hash — Aere pays the gas
|
|
const receipt = await aere.notarize('0x' + sha256Hex);
|
|
const proof = await aere.proofOf('0x' + sha256Hex); // { notarized, firstSeenAt, … }
|
|
|
|
// 1.2.0 (2026-09-17): the proof with its post-quantum finality: first appearance from the contract log,
|
|
// the anchor that covers it, a verdict, and how to verify every claim without Aere Cloud
|
|
const full = await aere.proof('0x' + sha256Hex); // { block, txHash, finality: 'post-quantum', pqAnchor: {…}, verify: {…} }
|
|
|
|
// quantum readiness of a domain's public TLS edge (free, no key); attest:true notarizes the report digest on chain
|
|
const scan = await aere.readiness('example.com'); // { score, verdict, summary, findings, … }
|
|
const attested = await aere.readiness('example.com', { attest: true }); // + attestation: { reportHash, txHash, proof, … }
|
|
// the whole public perimeter of a domain (1.3.0): named hosts + common prefixes found through DNS, one report; keyed
|
|
const perimeter = await aere.readinessPerimeter('example.com', { hosts: ['api', 'mail'] });
|
|
// perimeter.summary: { measured, withoutPqKeyExchange: [...], soonestCertificateExpiry, worstScore, verdict, complete }
|
|
// while summary.complete is false, call again: finished scans are cached; { attest: true } notarizes a complete report
|
|
// the audit log of a day as a FILE (1.4.0): the exact bytes whose sha256 is the digest you notarize; format: 'cef' for a SIEM
|
|
const file = await aere.auditExport({ day: '2026-09-17' }); // file.verified === true: sha256(file.bytes) is the stated digest
|
|
const fin = await aere.pqFinality('latest', 'testnet', 'both'); // AIP-21: { finality, agreement, postQuantumConfirmedByBoth, besu: {…}, nethermind: {…} }
|
|
|
|
// pqVerify: pass interface:'external' to verify a standard FIPS 204/205 signature (the precompile implements the
|
|
// internal interface; the gateway builds M' = 0x00 || len(ctx) || ctx || message for you)
|
|
const v = await aere.pqVerify({ scheme: 'ml-dsa-44', interface: 'external', publicKey, signature, message });
|
|
|
|
// Trust API (1.6.0): any AERE Proof Protocol (AIP-23) envelope -> VALID / INVALID / PARTIAL, judged by the published reference
|
|
// verifier, with the levels it checked and the command that reproduces the verdict. Served by cloud.aere.network since 2026-09-29.
|
|
const r = await aere.verify(envelope, { chain: 2800 }); // { verdict, levels: [{ level, state, detail }], verifier, reproduce }
|
|
|
|
// identity and compliance (1.7.0): an AERE Identity presentation (post-quantum credential, selective disclosure, bound to your audience
|
|
// and nonce) judged by the published command line; read `verdict` (PARTIAL: some rows could not be judged). No claims come back from
|
|
// complianceCheck; with record: true it returns the decision as an AIP-23 envelope without personal data, to notarize.
|
|
const id = await aere.identityVerify({ presentation, audience: 'https://your.app/verifier', nonce, trustedIssuers: [issuerId], statusLists: [list] });
|
|
const ok = await aere.complianceCheck({ presentation, policy, audience: 'https://your.app/verifier', nonce, statusLists: [list], record: true });
|
|
|
|
// transfer history for an address (token from genesis, native from launch)
|
|
const tx = await aere.transfers('0xYourAddress', 50);
|
|
|
|
// a smart account with a POST-QUANTUM owner (Falcon-512), gas sponsored:
|
|
const acct = await aere.sponsorCreatePqAccount('0x09' + falconPkHex, 0);
|
|
// -> { txHash, account: '0x…', alreadyDeployed: false }
|
|
```
|
|
|
|
A Python mirror of this client lives in `python/` (installed from this repository, see Install): same
|
|
routes, same semantics, snake_case names. `go/`, `java/` and `csharp/` carry the Go, Java and .NET clients.
|
|
|
|
Every method throws `AereCloudError` on a non-2xx response, carrying `.status` and the server's
|
|
JSON `.body` so you can act on the exact error.
|
|
|
|
## Webhooks
|
|
|
|
Create a webhook and verify every delivery — never trust a webhook payload without checking its
|
|
signature:
|
|
|
|
```js
|
|
import { AereCloud, verifyWebhook } from '@aere/cloud';
|
|
|
|
const aere = new AereCloud({ apiKey: process.env.AERE_KEY });
|
|
const wh = await aere.createWebhook({ type: 'pq-anchors', url: 'https://you.example/hook' });
|
|
// store wh.secret now — it is shown once
|
|
|
|
// in your webhook handler (raw body, not re-serialized):
|
|
app.post('/hook', async (req, res) => {
|
|
const ok = await verifyWebhook(req.rawBody, req.headers['x-aere-signature'], WEBHOOK_SECRET);
|
|
if (!ok) return res.status(401).end();
|
|
handle(JSON.parse(req.rawBody));
|
|
res.status(200).end();
|
|
});
|
|
```
|
|
|
|
Webhook types: `pq-anchors` (every 32nd-block certificate), `address-activity` (transactions
|
|
touching a watched address, pass `watch`), `subscription-events` (your billing events).
|
|
|
|
## Reference
|
|
|
|
Full API reference and OpenAPI spec: [aere.network/cloud-docs.html](https://aere.network/cloud-docs.html)
|
|
· live status you compute in your own browser: [aere.network/cloud-status.html](https://aere.network/cloud-status.html)
|
|
|
|
MIT licensed.
|