{ "openapi": "3.1.0", "info": { "title": "Aere Cloud API", "version": "1.7.0", "description": "Keyed JSON-RPC, post-quantum signature verification via chain-native precompiles, and chain data for Aere Network (chain 2800). Authentication is an API key whose keccak-256 hash lives in the on-chain AereCloudSubscriptionsV2 contract at 0xfA2375F5c30d25e0b952F5Ac07Bc292aD3C20433; the gateway validates every key against the chain and fails closed. WebSocket subscriptions (outside this REST spec) live at wss://cloud.aere.network/v1/ws with the same key, via x-api-key header or ?key= query. Human docs: https://aere.network/cloud-docs.html Changelog 2026-09-17: quantum readiness scan (free), attested readiness reports (keyed), Proof API with post-quantum finality, anchor schedule with dated steps (32 blocks from 13,014,000; 128 blocks from 17,225,968 since 2026-09-05) and per-scheme seal counts of the hybrid v2 certificate.", "contact": { "email": "office@aere.network", "url": "https://aere.network/cloud.html" } }, "servers": [ { "url": "https://cloud.aere.network/v1" } ], "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Format: ak2800.<0x address>.. Register keccak256 of the whole key string on-chain via AereCloudSubscriptionsV2.subscribe (free trial, or self-serve at listing), or have it granted by sales for invoice-paid plans." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string" }, "hint": { "type": "string" } }, "required": [ "error" ] }, "Anchor": { "type": "object", "description": "A block on the anchor grid. Heights: 13,014,000 + k*32 until 17,225,968, then 17,225,968 + k*128 (since 2026-09-05). \"anchored\" is measured from the header bytes (a 32-byte certificate digest in the extraData vanity field), never assumed from the height.", "properties": { "height": { "type": "integer" }, "hash": { "type": "string" }, "timestamp": { "type": "integer" }, "anchored": { "type": "boolean", "description": "true when the header carries the validators’ post-quantum certificate digest" }, "certificateVersion": { "type": "integer", "description": "1 = Falcon-512 only (until 2026-09-03); 2 = hybrid, each signer seals with Falcon-512 and SLH-DSA-128s; 0 when not anchored" }, "falconSeals": { "type": "integer", "description": "distinct validators that sealed with Falcon-512" }, "slhDsaSeals": { "type": "integer", "description": "distinct validators that sealed with SLH-DSA-128s (v2 only)" }, "signers": { "type": "integer", "description": "distinct validators in the certificate" }, "seals": { "type": "integer", "description": "total seals carried" }, "certificateDigest": { "type": [ "string", "null" ], "description": "32-byte certificate digest from the extraData vanity field, covered by the block hash; null when not anchored" } } }, "JsonRpcRequest": { "type": "object", "properties": { "jsonrpc": { "const": "2.0" }, "id": {}, "method": { "type": "string" }, "params": { "type": "array" } }, "required": [ "jsonrpc", "method" ] }, "AnchorScheduleStep": { "type": "object", "properties": { "fromBlock": { "type": "integer" }, "intervalBlocks": { "type": "integer" }, "since": { "type": "string", "description": "date the step took effect" } } }, "ReadinessReport": { "type": "object", "description": "Measured from five real TLS connections opened by the Aere Cloud host to port 443 of the domain. Cached for six hours per domain.", "properties": { "domain": { "type": "string" }, "measuredAt": { "type": "string" }, "from": { "type": "string" }, "addresses": { "type": "array", "items": { "type": "string" } }, "score": { "type": "integer", "minimum": 0, "maximum": 100 }, "verdict": { "type": "string" }, "summary": { "type": "object", "properties": { "tls13": { "type": "boolean" }, "pqKeyExchange": { "type": [ "string", "null" ], "description": "the hybrid post-quantum group negotiated, e.g. X25519MLKEM768, or null" }, "prefersPqWhenOffered": { "type": [ "boolean", "null" ] }, "tls12Accepted": { "type": "boolean" }, "hsts": { "type": [ "boolean", "null" ] }, "harvestNowDecryptLater": { "type": "string" }, "certificate": { "type": "object", "properties": { "keyType": { "type": "string" }, "bits": { "type": "integer" }, "issuer": { "type": "string" }, "validTo": { "type": "string" }, "daysLeft": { "type": "integer" } } } } }, "findings": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "severity": { "type": "string", "enum": [ "high", "medium", "low", "info" ] }, "title": { "type": "string" }, "detail": { "type": "string" }, "recommendation": { "type": "string" } } } }, "handshakes": { "type": "object" }, "method": { "type": "string" }, "cached": { "type": "boolean" } } }, "Attestation": { "type": "object", "description": "The SHA-256 digest of reportJson, notarized on chain 2800. Recompute sha256(reportJson) in any language: it equals reportHash.", "properties": { "reportHash": { "type": "string" }, "digest": { "type": "string" }, "reportJson": { "type": "string" }, "txHash": { "type": "string" }, "block": { "type": "integer" }, "firstSeenAt": { "type": "integer" }, "firstTime": { "type": "boolean" }, "contract": { "type": "string" }, "chainId": { "const": 2800 }, "proof": { "type": "string", "description": "path of the Proof API record: /v1/proof/{reportHash}" }, "note": { "type": "string" } } }, "Proof": { "type": "object", "properties": { "hash": { "type": "string" }, "notarized": { "type": "boolean" }, "firstSeenAt": { "type": "integer" }, "firstSeenIso": { "type": "string" }, "block": { "type": [ "integer", "null" ], "description": "block of the first appearance, from the contract’s Notarized event log" }, "blockHash": { "type": [ "string", "null" ] }, "txHash": { "type": [ "string", "null" ] }, "confirmations": { "type": [ "integer", "null" ] }, "head": { "type": "integer" }, "finality": { "type": "string", "enum": [ "post-quantum", "pending", "first-seen-only", "anchor-without-certificate" ], "description": "post-quantum once the covering anchor exists and carries a certificate; pending until then" }, "pqAnchor": { "oneOf": [ { "$ref": "#/components/schemas/Anchor" }, { "type": "null" } ], "description": "the first anchor block at or after the first appearance" }, "pqAnchorExpectedAt": { "type": [ "integer", "null" ], "description": "height of the covering anchor when it is not yet produced" }, "pqAnchorsSince": { "type": "integer", "description": "anchors produced since the first appearance" }, "contract": { "type": "string" }, "chainId": { "const": 2800 }, "verify": { "type": "object", "description": "how to check each claim on any chain-2800 node and with the public anchor verifier, without Aere Cloud", "properties": { "firstSeenAt": { "type": "string" }, "firstAppearance": { "type": "string" }, "pqAnchor": { "type": "string" }, "meaning": { "type": "string" } } } } }, "AuditEntry": { "type": "object", "properties": { "t": { "type": "string", "description": "ISO time of the response" }, "m": { "type": "string" }, "p": { "type": "string", "description": "request path" }, "s": { "type": "integer", "description": "HTTP status returned" }, "truncated": { "type": "boolean", "description": "present once per day when the per-account cap was reached" } } }, "PqSeal": { "type": "object", "properties": { "scheme": { "type": "string", "enum": [ "falcon-512", "slh-dsa-sha2-128s" ] }, "index": { "type": "integer", "description": "validator index in the anchored registry epoch" }, "verified": { "type": [ "boolean", "null" ], "description": "true/false for Falcon-512 seals re-verified now; null for hybrid extras, which the anchor certificate verifies" }, "signature": { "type": "string" } } }, "PqFinality": { "type": "object", "description": "AIP-21: the post-quantum finality record of one block, answered by a validator (seals travel only between validators) and re-verified now against the anchored registry over signedMessage.", "properties": { "network": { "type": "string" }, "chainId": { "type": "integer" }, "blockNumber": { "type": "integer" }, "blockHash": { "type": "string" }, "validators": { "type": "integer" }, "quorum": { "type": "integer", "description": "the chain’s commit quorum for that validator count" }, "sealForm": { "type": "string", "enum": [ "anchor", "commit-digest" ] }, "signedMessage": { "type": [ "string", "null" ] }, "falconSealsHeard": { "type": "integer" }, "falconSealsVerified": { "type": "integer", "description": "distinct validators whose Falcon-512 seal verifies now" }, "verifiedIndexes": { "type": "array", "items": { "type": "integer" } }, "falconSeals": { "type": "array", "items": { "$ref": "#/components/schemas/PqSeal" } }, "hybridSeals": { "type": "array", "items": { "$ref": "#/components/schemas/PqSeal" } }, "finality": { "type": "string", "enum": [ "post-quantum", "partial", "none", "unavailable", "unverifiable-form" ] }, "retentionBlocks": { "type": "integer" }, "note": { "type": "string" }, "answeredBy": { "type": "string" }, "source": { "type": "string" }, "aip": { "const": "AIP-21" } } }, "AdoptionShare": { "type": "object", "properties": { "yes": { "type": "integer" }, "of": { "type": "integer" }, "share": { "type": [ "number", "null" ], "description": "percent, one decimal" }, "ci95": { "type": [ "array", "null" ], "items": { "type": "number" }, "description": "Wilson 95% interval, percent" } } }, "AdoptionEdition": { "type": "object", "properties": { "series": { "type": "string" }, "edition": { "type": "string", "format": "date" }, "startedAt": { "type": "string" }, "finishedAt": { "type": "string" }, "measuredFrom": { "type": "string" }, "list": { "type": "object", "properties": { "source": { "type": "string" }, "id": { "type": "string" }, "createdOn": { "type": "string" }, "url": { "type": "string" } } }, "method": { "type": "string" }, "sectors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "rule": { "type": "string" }, "status": { "type": "string", "enum": [ "measured", "not-measured" ] }, "selected": { "type": "integer" }, "measured": { "type": "integer" }, "notMeasured": { "type": "object", "additionalProperties": { "type": "integer" } }, "pqKeyExchange": { "$ref": "#/components/schemas/AdoptionShare" }, "prefersPqWhenOffered": { "$ref": "#/components/schemas/AdoptionShare" }, "tls13": { "$ref": "#/components/schemas/AdoptionShare" }, "tls12StillAccepted": { "$ref": "#/components/schemas/AdoptionShare" }, "hsts": { "$ref": "#/components/schemas/AdoptionShare" } } } }, "commitment": { "type": "object", "properties": { "sha256": { "type": "string" }, "lines": { "type": "integer" }, "note": { "type": "string" } } } } } }, "responses": { "e401": { "description": "Missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "e403": { "description": "Invalid or expired key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "e429": { "description": "Over the plan's per-second limit; Retry-After: 1", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "e503": { "description": "Subscription could not be verified on-chain; the gateway fails closed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "security": [ { "apiKey": [] } ], "paths": { "/health": { "get": { "summary": "Liveness and chain head; the only unauthenticated route", "security": [], "responses": { "200": { "description": "Gateway and node are healthy", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "chainId": { "const": 2800 }, "block": { "type": "integer" } } }, "example": { "ok": true, "chainId": 2800, "block": 15220078 } } } } } } }, "/rpc": { "post": { "summary": "JSON-RPC 2.0 on chain 2800 (single or batch)", "description": "Allowed: eth_*, net_*, web3_*, qbft_getValidatorsByBlockNumber, qbft_getValidatorsByBlockHash, qbft_getSignerMetrics, qbft_getPendingVotes. Anything else answers a JSON-RPC error -32601 in place, preserving batch positions.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/JsonRpcRequest" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonRpcRequest" } } ] } } } }, "responses": { "200": { "description": "JSON-RPC response from the node" }, "401": { "$ref": "#/components/responses/e401" }, "403": { "$ref": "#/components/responses/e403" }, "429": { "$ref": "#/components/responses/e429" }, "503": { "$ref": "#/components/responses/e503" } } } }, "/pq/verify": { "post": { "summary": "Verify a NIST post-quantum signature via the chain's native precompiles; interface:\"external\" verifies standard FIPS 204/205 signatures", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "scheme": { "enum": [ "ml-dsa-44", "slh-dsa-128s", "falcon-512", "falcon-1024" ] }, "publicKey": { "type": "string", "description": "0x-prefixed hex" }, "signature": { "type": "string", "description": "0x hex; ml-dsa-44 and slh-dsa-128s only" }, "message": { "type": "string", "description": "0x hex; ml-dsa-44 and slh-dsa-128s only" }, "signedMessage": { "type": "string", "description": "0x hex Falcon reference signed-message blob; falcon-512 and falcon-1024 only" }, "interface": { "type": "string", "enum": [ "internal", "external" ], "default": "internal", "description": "ML-DSA / SLH-DSA only. \"internal\": the message is verified exactly as given (FIPS internal interface, what the precompile implements). \"external\": the gateway builds the FIPS 204/205 external encoding M' = 0x00 || len(context) || context || message, so a standard signature from any library, HSM or the AIP-20 tooling verifies. Measured on chain for ML-DSA-44 on 2026-09-17; SLH-DSA-128s follows FIPS 205 but is not yet measured against an external vector." }, "context": { "type": "string", "description": "0x-hex, at most 255 bytes; only with interface:\"external\"; defaults to empty" } }, "required": [ "scheme", "publicKey" ] }, "example": { "scheme": "ml-dsa-44", "publicKey": "0x…", "signature": "0x…", "message": "0x…" } } } }, "responses": { "200": { "description": "Verdict computed on-chain", "content": { "application/json": { "example": { "valid": true, "scheme": "ml-dsa-44", "precompile": "0x0000000000000000000000000000000000000ae3", "block": 15220111, "chainId": 2800 } } } }, "400": { "description": "Malformed input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/e401" }, "403": { "$ref": "#/components/responses/e403" }, "429": { "$ref": "#/components/responses/e429" }, "503": { "$ref": "#/components/responses/e503" } } } }, "/account": { "get": { "summary": "Your subscription and usage over the last 31 days", "responses": { "200": { "description": "Account state", "content": { "application/json": { "example": { "address": "0xbeb3…6465", "planId": 0, "plan": { "name": "rpc-build", "monthlyPriceWei": "980000000000000000000", "active": true }, "expiresAt": 1790065218, "expiresAtIso": "2026-09-22T08:20:18.000Z", "usageLast31Days": { "rpc": 1204, "pq": 37, "data": 12 }, "contract": "0xfa2375f5c30d25e0b952f5ac07bc292ad3c20433", "chainId": 2800 } } } }, "401": { "$ref": "#/components/responses/e401" }, "403": { "$ref": "#/components/responses/e403" } } } }, "/data/head": { "get": { "summary": "Chain head with timestamp and base fee", "responses": { "200": { "description": "Head", "content": { "application/json": { "example": { "chainId": 2800, "block": 15225986, "hash": "0x6539…a3b0", "timestamp": 1787477821, "baseFeeWei": "1000000000" } } } }, "401": { "$ref": "#/components/responses/e401" } } } }, "/data/validators": { "get": { "summary": "The live QBFT validator set, read from consensus", "responses": { "200": { "description": "Validator set", "content": { "application/json": { "example": { "chainId": 2800, "count": 9, "validators": [ "0x1bd5…", "0x4bf6…" ] } } } }, "401": { "$ref": "#/components/responses/e401" } } } }, "/data/finality": { "get": { "summary": "The post-quantum finality point of the chain: finalized/safe = the parent of the most recent anchor whose certificate reaches the threshold in force (AIP-15/22); nothing between anchors is final", "responses": { "200": { "description": "Finality point", "content": { "application/json": { "schema": { "type": "object", "properties": { "chainId": { "type": "integer" }, "head": { "type": "integer" }, "finalized": { "type": "integer" }, "finalizedHash": { "type": "string" }, "safe": { "type": "integer" }, "safeHash": { "type": "string" }, "anchor": { "type": "integer" }, "anchorHash": { "type": "string" }, "threshold": { "type": "integer" }, "lagBlocks": { "type": "integer" }, "certificate": { "type": "object", "properties": { "version": { "type": "integer" }, "falconSeals": { "type": "integer" }, "slhDsaSeals": { "type": "integer" }, "signers": { "type": "integer" }, "digest": { "type": "string" } } }, "verified": { "type": "string", "enum": [ "presence-and-threshold" ] }, "note": { "type": "string" } } } } } }, "503": { "description": "no_certified_anchor: none of the recent anchor heights carries a certificate reaching the threshold" } } } }, "/data/anchors": { "get": { "summary": "Latest post-quantum anchor certificates, newest first", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 } } ], "responses": { "200": { "description": "Anchors", "content": { "application/json": { "schema": { "type": "object", "properties": { "chainId": { "const": 2800 }, "head": { "type": "integer" }, "anchorIntervalBlocks": { "type": "integer", "description": "the interval in force at the head (128 since 2026-09-05)" }, "firstAnchorBlock": { "const": 13014000 }, "anchors": { "type": "array", "items": { "$ref": "#/components/schemas/Anchor" } }, "anchorSchedule": { "type": "array", "items": { "$ref": "#/components/schemas/AnchorScheduleStep" } }, "note": { "type": "string" } } }, "example": { "chainId": 2800, "head": 19018276, "anchorIntervalBlocks": 128, "firstAnchorBlock": 13014000, "anchorSchedule": [ { "fromBlock": 13014000, "intervalBlocks": 32, "since": "2026-08-05" }, { "fromBlock": 17225968, "intervalBlocks": 128, "since": "2026-09-05" } ], "universalSince": 13889296, "anchors": [ { "height": 19018224, "hash": "0x2b4547d0d51a9a6ff603b5113203c796c4c9cd7e5151980698d236413f96f297", "timestamp": 1789679371, "anchored": true, "certificateVersion": 2, "falconSeals": 9, "slhDsaSeals": 9, "signers": 9, "seals": 18, "certificateDigest": "0x45f311a028a5b77e38caa574555a00a4d8ef3f99a5b7e78e008c264e430db0ff" } ] } } } }, "401": { "$ref": "#/components/responses/e401" } } } }, "/data/anchors/{height}": { "get": { "summary": "One anchor by height (400 not_an_anchor_height when the height is not on the dated anchor grid; the hint carries the rule and anchorSchedule)", "parameters": [ { "name": "height", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "The anchor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Anchor" } } } }, "400": { "description": "Not an anchor height", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/e401" }, "404": { "description": "Block not found" } } } }, "/webhooks": { "get": { "summary": "List your webhooks (secrets masked)", "responses": { "200": { "description": "Webhook list" }, "401": { "$ref": "#/components/responses/e401" } } }, "post": { "summary": "Create a webhook (max 5 per account; public http(s) targets only)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "enum": [ "pq-anchors", "subscription-events", "address-activity", "quantum-readiness", "quantum-perimeter" ] }, "url": { "type": "string" }, "address": { "type": "string", "description": "watched 0x address; address-activity only" }, "domain": { "type": "string", "description": "hostname to monitor; quantum-readiness only. The readiness scan is repeated every six hours; the first report is delivered as a baseline, then only changes (post-quantum key exchange, preference, TLS 1.2, HSTS, findings, certificate expiry crossing 30/14/7/1 days) or a measurement error." } }, "required": [ "type", "url" ] } } } }, "responses": { "201": { "description": "Created; the HMAC secret is returned once" }, "400": { "description": "Bad type/url/address, or private target refused" }, "401": { "$ref": "#/components/responses/e401" }, "409": { "description": "Webhook limit reached" } } } }, "/webhooks/{id}": { "delete": { "summary": "Delete one of your webhooks", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted" }, "401": { "$ref": "#/components/responses/e401" }, "404": { "description": "Not yours or not found" } } } }, "/notarize": { "post": { "summary": "Notarize a 32-byte digest on-chain (we pay the gas); first-seen is immutable", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "hash": { "type": "string", "description": "0x + 64 hex chars" } }, "required": [ "hash" ] } } } }, "responses": { "200": { "description": "Receipt with txHash, block, firstSeenAt, firstTime" }, "400": { "description": "Malformed hash" }, "401": { "$ref": "#/components/responses/e401" }, "503": { "description": "Notary temporarily unavailable" } } } }, "/notarize/{hash}": { "get": { "summary": "Read the on-chain proof for a digest", "parameters": [ { "name": "hash", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "notarized flag with firstSeenAt/firstSeenIso, and proof: the path of the Proof API record" }, "401": { "$ref": "#/components/responses/e401" } } } }, "/data/transfers": { "get": { "summary": "Transfers touching an address: token from genesis, native from launch (boundaries in the response)", "parameters": [ { "name": "address", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "tokenTransfers + nativeTransfers with tokenHistoryComplete and nativeSince" }, "400": { "description": "Missing or malformed address" }, "401": { "$ref": "#/components/responses/e401" } } } }, "/sponsor/createAccount": { "post": { "summary": "Deploy a user's passkey smart account; the Foundation relayer pays the gas (metered per API key)", "responses": { "200": { "description": "Account deployed" }, "400": { "description": "Relayer validation error" }, "401": { "$ref": "#/components/responses/e401" }, "503": { "description": "Relayer unavailable" } } } }, "/sponsor/execute": { "post": { "summary": "Submit a user's signed operation via the sponsoring relayer", "responses": { "200": { "description": "Submitted" }, "400": { "description": "Relayer validation error" }, "401": { "$ref": "#/components/responses/e401" }, "503": { "description": "Relayer unavailable" } } } }, "/sponsor/health": { "get": { "summary": "Relayer liveness and gas balance", "responses": { "200": { "description": "ok with balance_aere" }, "401": { "$ref": "#/components/responses/e401" } } } }, "/pq/readiness": { "post": { "summary": "Quantum readiness scan of a domain’s public TLS edge (free, no key); with attest:true and a key, the report digest is notarized on chain", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "domain" ], "properties": { "domain": { "type": "string", "description": "hostname (no scheme, no path)" }, "fresh": { "type": "boolean", "description": "bypass the six-hour cache (rate limited)" }, "attest": { "type": "boolean", "description": "notarize the SHA-256 of the report on chain 2800; requires x-api-key; counted as one data request" } } }, "example": { "domain": "aere.network" } } } }, "responses": { "200": { "description": "The measured report; with attest:true also an attestation object", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ReadinessReport" }, { "type": "object", "properties": { "attestation": { "$ref": "#/components/schemas/Attestation" } } } ] }, "example": { "domain": "aere.network", "measuredAt": "2026-09-17T20:48:44.940Z", "from": "AERE Cloud, EU (Helsinki)", "addresses": [ "2606:4700:3036::6815:364b", "2606:4700:3031::ac43:8864", "104.21.54.75", "172.67.136.100" ], "score": 75, "verdict": "partially prepared", "summary": { "tls13": true, "pqKeyExchange": "X25519MLKEM768", "prefersPqWhenOffered": false, "tls12Accepted": true, "hsts": false, "harvestNowDecryptLater": "protected for TLS 1.3 clients that offer the hybrid group", "certificate": { "keyType": "EC/prime256v1", "bits": 256, "issuer": "Let's Encrypt", "validTo": "Nov 26 13:50:47 2026 GMT", "daysLeft": 69 } }, "findings": [ { "id": "pq-not-preferred", "severity": "medium", "title": "Post-quantum key exchange is supported but not preferred", "detail": "With X25519MLKEM768 offered first alongside classical groups, the server picked X25519MLKEM768.", "recommendation": "Order the hybrid group first in the server preference list so every capable client gets it." }, { "id": "tls12-accepted", "severity": "medium", "title": "TLS 1.2 is still accepted", "detail": "A TLS 1.2-only client was served (ECDHE-ECDSA-AES128-GCM-SHA256). Such sessions never get post-quantum key exchange.", "recommendation": "Retire TLS 1.2 once your client population allows it, or at least prefer TLS 1.3." }, { "id": "hsts-missing", "severity": "low", "title": "No HSTS header", "detail": "Strict-Transport-Security is absent on the front page, so a first visit can be downgraded to plaintext.", "recommendation": "Send Strict-Transport-Security with a max-age of at least one year." }, { "id": "auth-classical", "severity": "info", "title": "Certificate authentication is classical (EC/prime256v1-256)", "detail": "Every public web certificate today is signed with ECDSA or RSA; a quantum adversary could forge such signatures in the future, but unlike encryption this cannot be exploited retroactively on recorded traffic.", "recommendation": "Keep certificate agility: short-lived, automatically issued certificates, so switching to hybrid or post-quantum certificates is a configuration change when CAs offer them." } ], "cached": true } } } }, "400": { "description": "bad_domain, or a report with error dns / no_tls when the host cannot be measured" }, "401": { "description": "attest:true without a key (the scan itself needs none)" }, "403": { "$ref": "#/components/responses/e403" }, "429": { "$ref": "#/components/responses/e429" }, "503": { "$ref": "#/components/responses/e503" } } } }, "/pq/readiness/{domain}": { "get": { "summary": "The latest cached report for a domain (free, no key); measures it when none is cached", "security": [], "parameters": [ { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadinessReport" } } } }, "400": { "description": "bad_domain" }, "503": { "$ref": "#/components/responses/e503" } } } }, "/pq/readiness/perimeter": { "post": { "summary": "Quantum readiness of the whole public perimeter of a domain: named hosts plus common prefixes found through DNS, one report", "description": "Keyed. Every host found is measured with the same handshakes as POST /pq/readiness, at most 16 per report, 4 at a time. The request has a deadline: hosts still being measured are returned in `pending` with summary.complete=false; call again (finished scans are cached for 6 hours). The summary is derived from measured hosts only. Hosts must be the domain or under it; a host resolving to a non-public address is refused and never connected to; in a wildcard-DNS zone guessed prefixes that echo the wildcard are dropped. attest=true notarizes the digest of a COMPLETE report on chain 2800.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "domain" ], "properties": { "domain": { "type": "string", "description": "a public domain name, no scheme, no path" }, "hosts": { "type": "array", "maxItems": 16, "items": { "type": "string" }, "description": "labels (api) or full names that are the domain or under it" }, "discover": { "type": "boolean", "default": true, "description": "try common prefixes through DNS" }, "attest": { "type": "boolean", "default": false } } } } } }, "responses": { "200": { "description": "The perimeter report (with `attestation` when attest=true)", "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string" }, "generatedAt": { "type": "string", "format": "date-time" }, "summary": { "type": "object", "properties": { "hostsFound": { "type": "integer" }, "measured": { "type": "integer" }, "pending": { "type": "integer" }, "withoutTls": { "type": "array", "items": { "type": "string" } }, "failedTransient": { "type": "integer" }, "notScannedOverLimit": { "type": "integer" }, "withPqKeyExchange": { "type": "integer" }, "withoutPqKeyExchange": { "type": "array", "items": { "type": "string" } }, "tls12Accepted": { "type": "array", "items": { "type": "string" } }, "worstScore": { "type": [ "integer", "null" ] }, "averageScore": { "type": [ "integer", "null" ] }, "soonestCertificateExpiry": { "type": [ "object", "null" ] }, "verdict": { "type": "string" }, "complete": { "type": "boolean" } } }, "hosts": { "type": "array", "items": { "type": "object", "properties": { "host": { "type": "string" }, "measured": { "type": "boolean" }, "error": { "type": "string", "description": "when measured is false: no_tls and dns are definitive, rate_limited and readiness_unavailable are transient" }, "score": { "type": "integer" }, "verdict": { "type": "string" }, "pqKeyExchange": { "type": [ "string", "null" ] }, "prefersPqWhenOffered": { "type": [ "boolean", "null" ] }, "tls13": { "type": "boolean" }, "tls12Accepted": { "type": "boolean" }, "hsts": { "type": [ "boolean", "null" ] }, "certificate": { "type": "object", "properties": { "keyType": { "type": [ "string", "null" ] }, "issuer": { "type": [ "string", "null" ] }, "validTo": { "type": [ "string", "null" ] }, "daysLeft": { "type": [ "integer", "null" ] } } }, "findings": { "type": "array", "items": { "type": "string" } }, "measuredAt": { "type": "string" }, "cached": { "type": "boolean" }, "report": { "type": "string" } } } }, "pending": { "type": "array", "items": { "type": "string" } }, "notFound": { "type": "array", "items": { "type": "string" } }, "refused": { "type": "array", "items": { "type": "object" } }, "notScannedOverLimit": { "type": "array", "items": { "type": "string" } }, "discovery": { "type": "object", "properties": { "tried": { "type": "integer" }, "wildcardDns": { "type": "boolean" }, "wildcardEchoesDropped": { "type": "integer" }, "note": { "type": "string" } } }, "attestation": { "type": "object" }, "note": { "type": "string" } } } } } }, "400": { "description": "bad_json, bad_domain, bad_hosts, or host_outside_domain" }, "401": { "description": "missing_api_key" }, "403": { "description": "invalid_or_expired_key" }, "409": { "description": "attest=true on an incomplete report: perimeter_incomplete (the report is still returned)" }, "429": { "description": "rate_limit" }, "503": { "description": "readiness_unavailable (temporary)" } } } }, "/proof/{hash}": { "get": { "summary": "Proof of a notarized digest with its post-quantum finality: first appearance, covering anchor, verdict, independent verification steps", "parameters": [ { "name": "hash", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } } ], "responses": { "200": { "description": "The proof record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Proof" }, "example": { "hash": "0x367a1967df839dab40e2a62e053a38950e759f90b26aa87a259d38cb784e021d", "notarized": true, "firstSeenAt": 1789679286, "firstSeenIso": "2026-09-17T21:08:06.000Z", "block": 19018082, "blockHash": "0xc5fb8eb6bf9a9529bc0f774aa41168f9422b3c4667b7b933ceb146ad797acba9", "txHash": "0x0c9934f987552580a5aeb3d76a6c18e8c2020282ee4cf5613cdc7dd996680ef1", "confirmations": 194, "head": 19018276, "finality": "post-quantum", "pqAnchor": { "height": 19018096, "hash": "0xf776f80e1710dc0e0f1927958dd589b98fc35ce8b9854e4fdb12320459fbb3f1", "timestamp": 1789679295, "anchored": true, "certificateVersion": 2, "falconSeals": 9, "slhDsaSeals": 9, "signers": 9, "seals": 18, "certificateDigest": "0x19c4cdbbac8e2ac1c42c24679c31b22c37d3d03ba439d2d6e6a5ba2486bcf870" }, "pqAnchorExpectedAt": null, "pqAnchorsSince": 2, "contract": "0x4ab392c4aca7d9d4c16c0b60a9514c5025bd58c7", "chainId": 2800, "verify": { "firstSeenAt": "eth_call to 0x4ab392c4aca7d9d4c16c0b60a9514c5025bd58c7 with data 0xe11f8d00 on any chain-2800 node returns the first-seen unix time; it can never be overwritten", "firstAppearance": "eth_getLogs address 0x4ab392c4aca7d9d4c16c0b60a9514c5025bd58c7, topics [0x9b44743b380b5acfe572d65073d98fd4645754188e1878eb9db3b8ed53a1d678, ] at block 19018082", "pqAnchor": "the header of block 19018096 carries the validators' post-quantum certificate under its hash; verify it without us: https://aere.network/tools/verify-anchor.mjs (node verify-anchor.mjs 19018096)", "meaning": "after the anchor, rewriting the block that holds this proof would require forging a post-quantum validator certificate, not only classical ECDSA keys" } } } } }, "401": { "$ref": "#/components/responses/e401" }, "404": { "description": "notarized:false (POST /v1/notarize first)" }, "503": { "$ref": "#/components/responses/e503" } } } }, "/account/audit": { "get": { "summary": "Audit log of every keyed request of this account for one UTC day (append-only file, paged), with the SHA-256 digest of the day file", "parameters": [ { "name": "day", "in": "query", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "description": "UTC day, default today" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 5000, "default": 1000 } }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "json", "jsonl", "cef" ], "default": "json" }, "description": "json: the paged JSON view. jsonl: the exact bytes of the day file (application/x-ndjson); the header x-aere-digest is the SHA-256 of those bytes, which is the digest to notarize. cef: the same entries as ArcSight CEF lines (text/plain) for a SIEM, with the digest of the source file in x-aere-digest. offset and limit apply to json only." } ], "responses": { "200": { "description": "The page", "content": { "application/json": { "schema": { "type": "object", "properties": { "account": { "type": "string" }, "day": { "type": "string" }, "total": { "type": "integer" }, "offset": { "type": "integer" }, "limit": { "type": "integer" }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/AuditEntry" } }, "digest": { "type": [ "string", "null" ], "description": "sha256 of the whole day file; notarize it (POST /notarize) to make the log tamper-evident with post-quantum finality" }, "digestOf": { "type": "string" }, "maxPerDay": { "const": 200000 }, "note": { "type": "string" } } } }, "application/x-ndjson": { "schema": { "type": "string", "description": "the day file, one JSON object per line: {t, m, p, s}" } }, "text/plain": { "schema": { "type": "string", "description": "one CEF:0 line per entry; severity 1 (2xx), 5 (4xx), 6 (401, 403, 429), 8 (5xx)" } } }, "headers": { "x-aere-day": { "schema": { "type": "string" } }, "x-aere-entries": { "schema": { "type": "integer" } }, "x-aere-digest": { "schema": { "type": "string" }, "description": "jsonl and cef: SHA-256 of the day file (for jsonl, of the bytes served)" }, "x-aere-cef-lines": { "schema": { "type": "integer" }, "description": "cef only" } } }, "400": { "description": "bad_day; bad_format for an unknown format" }, "401": { "$ref": "#/components/responses/e401" }, "403": { "$ref": "#/components/responses/e403" }, "410": { "description": "audit_day_expired: the day was deleted under the retention you set; the body carries its tombstone (day, digest, entries, bytes, deletedAt, retentionDays)" }, "429": { "$ref": "#/components/responses/e429" } } } }, "/console/account": { "post": { "summary": "Console sign-in with a wallet signature (no API key): the account view, the security command center, and webhook management", "description": "Sign the exact text `Aere Cloud console login\\naddress: <0x address, lowercase>\\ntimestamp: ` with the account's wallet (personal_sign, EIP-191). The gateway rebuilds the message and recovers the signer through the chain's ecrecover precompile; the timestamp must be within 10 minutes. Without an action the response is the account view (subscription, usage, on-chain receipt history). With securityAction=overview it is the security view: six measured checks, the API key age from its last on-chain key event, the hostnames under quantum-readiness monitoring with their last measured report and certificate days left, the digests this account notarized with the finality read from the covering anchor header, the audit log of the last 7 days with each day digest and whether it was notarized, and the webhook health. With webhookAction the account webhooks are managed with the same signature. Read-only apart from webhookAction create/delete.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "address", "timestamp", "signature" ], "properties": { "address": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "timestamp": { "type": "integer", "description": "unix seconds, within 600 s of the gateway clock" }, "signature": { "type": "string", "description": "65-byte personal_sign signature, 0x-prefixed hex" }, "securityAction": { "type": "string", "enum": [ "overview" ] }, "webhookAction": { "type": "string", "enum": [ "list", "create", "delete" ] }, "type": { "type": "string", "description": "webhookAction=create: the webhook type, as in POST /webhooks" }, "url": { "type": "string" }, "watch": { "type": "string", "description": "address-activity: the 0x address to watch (alias: address)" }, "domain": { "type": "string", "description": "quantum-readiness: the hostname to monitor" }, "id": { "type": "string", "description": "webhookAction=delete" } } } } } }, "responses": { "200": { "description": "The account view, or with securityAction=overview the security view", "content": { "application/json": { "schema": { "type": "object", "properties": { "address": { "type": "string" }, "generatedAt": { "type": "string", "format": "date-time" }, "head": { "type": "integer" }, "passed": { "type": "integer" }, "failed": { "type": "integer" }, "unknown": { "type": "integer" }, "checks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "api-key-rotated", "hosts-monitored", "pq-key-exchange", "certificates", "audit-notarized", "webhooks-healthy" ] }, "pass": { "type": [ "boolean", "null" ], "description": "true, false, or null when it cannot be told from what is held (no measured report yet, no closed day); null counts neither as passed nor as failed" }, "title": { "type": "string" }, "detail": { "type": "string" }, "fix": { "type": "string" } } } }, "apiKey": { "type": "object" }, "hosts": { "type": "array", "items": { "type": "object" } }, "proofs": { "type": "object", "properties": { "total": { "type": "integer" }, "distinct": { "type": "integer" }, "latest": { "type": "array", "items": { "type": "object", "properties": { "hash": { "type": "string" }, "kind": { "type": "string", "enum": [ "notarize", "readiness-attestation" ] }, "block": { "type": [ "integer", "null" ] }, "txHash": { "type": [ "string", "null" ] }, "finality": { "type": "string", "enum": [ "post-quantum", "pending", "anchor-without-certificate", "first-seen-only", "unknown" ] }, "pqAnchor": { "type": [ "object", "null" ] }, "proof": { "type": "string" } } } } } }, "audit": { "type": "object" }, "webhooks": { "type": "object" } } } } } }, "201": { "description": "webhookAction=create: the webhook, with its secret shown once" }, "400": { "description": "bad_json, bad_address, bad_action, bad_type, bad_domain or a refused webhook target" }, "401": { "description": "stale_timestamp, or bad_signature (the signer is not the address)" }, "429": { "description": "rate_limit" }, "503": { "description": "signature_check_unavailable or console_unavailable (temporary)" } } } }, "/pq/finality": { "get": { "summary": "AIP-21: per-block post-quantum finality record (seals heard by a validator, re-verified now, quorum verdict); free, no key; testnet 28001 first; client=besu|nethermind|both, with two-client agreement", "security": [], "parameters": [ { "name": "network", "in": "query", "schema": { "type": "string", "enum": [ "testnet" ], "default": "testnet" } }, { "name": "client", "in": "query", "description": "Which validator implementation answers: besu (default), nethermind, or both. With both, the record carries the two records side by side plus agreement (blockHash, finality and quorum equal), the property no single-client network can offer.", "schema": { "type": "string", "enum": [ "besu", "nethermind", "both" ], "default": "besu" } } ], "responses": { "200": { "description": "The record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PqFinality" } } } }, "400": { "description": "unsupported_network or unsupported_client" }, "404": { "description": "block_not_found" }, "502": { "description": "finality_door_error" }, "503": { "$ref": "#/components/responses/e503" } } } }, "/pq/finality/{block}": { "get": { "summary": "AIP-21: per-block post-quantum finality record (seals heard by a validator, re-verified now, quorum verdict); free, no key; testnet 28001 first; client=besu|nethermind|both, with two-client agreement", "security": [], "parameters": [ { "name": "block", "in": "path", "required": true, "schema": { "type": "string" }, "description": "block number or \"latest\" (default)" }, { "name": "network", "in": "query", "schema": { "type": "string", "enum": [ "testnet" ], "default": "testnet" } }, { "name": "client", "in": "query", "description": "Which validator implementation answers: besu (default), nethermind, or both. With both, the record carries the two records side by side plus agreement (blockHash, finality and quorum equal), the property no single-client network can offer.", "schema": { "type": "string", "enum": [ "besu", "nethermind", "both" ], "default": "besu" } } ], "responses": { "200": { "description": "The record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PqFinality" } } } }, "400": { "description": "unsupported_network or unsupported_client" }, "404": { "description": "block_not_found" }, "502": { "description": "finality_door_error" }, "503": { "$ref": "#/components/responses/e503" } } } }, "/pq/adoption": { "get": { "summary": "The latest weekly post-quantum adoption edition: sector aggregates only (free, no key)", "security": [], "responses": { "200": { "description": "The edition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdoptionEdition" } } } }, "404": { "description": "no_edition" }, "503": { "$ref": "#/components/responses/e503" } } } }, "/pq/adoption/{date}": { "get": { "summary": "A dated edition (YYYY-MM-DD) of the post-quantum adoption series (free, no key)", "security": [], "parameters": [ { "name": "date", "in": "path", "required": true, "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "The edition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdoptionEdition" } } } }, "404": { "description": "no_edition" }, "503": { "$ref": "#/components/responses/e503" } } } }, "/account/audit/retention": { "get": { "summary": "Retention of the audit log (read-only with the API key)", "description": "What is in force (retentionDays, null = keep every day; hold), what is pending and from when (a change that deletes more waits 7 days), what is held, and the retention ledger: every change and every deleted day with its digest. Set only with a wallet signature in the console (auditAction setRetention on POST /console/account).", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "the retention view of the account", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "missing API key" }, "403": { "description": "invalid or expired key" } } }, "post": { "summary": "Refused: retention is not set with the API key", "responses": { "405": { "description": "read_only_with_api_key: set retention with a wallet signature in the console" } } } }, "/verify": { "post": { "summary": "Trust API: verify one AERE Proof Protocol (AIP-23) envelope of any kind; VALID / INVALID / PARTIAL with every level checked, judged by the published reference verifier (verify-proof.mjs)", "parameters": [ { "name": "chain", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 2800, 28001 ] }, "description": "network whose notary and post-quantum anchors are read; by default the one the envelope's notarization declares (when it is a known notary), else 2800" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "one AIP-23 envelope { v, kind, statement, statementHash, signature?, notarization? }, at most 64 KB", "required": [ "statement", "statementHash" ], "properties": { "v": { "type": "integer" }, "kind": { "type": "string" }, "statement": { "type": "object" }, "statementHash": { "type": "string", "description": "0x + 64 hex: sha256 of the canonical statement" }, "signature": { "type": "object" }, "notarization": { "type": "object" } } } } } }, "responses": { "200": { "description": "The reference verifier's verdict. VALID: every level present passed; INVALID: a level present failed; PARTIAL: a level present could not be measured. A level the envelope does not carry is ABSENT, never counted as passed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "verdict": { "enum": [ "VALID", "INVALID", "PARTIAL" ] }, "statementHash": { "type": "string" }, "levels": { "type": "array", "items": { "type": "object", "properties": { "level": { "enum": [ "form", "integrity", "signature", "finality" ] }, "state": { "enum": [ "PASSED", "FAILED", "ABSENT", "UNMEASURED" ] }, "detail": { "type": "string" } } } }, "verifier": { "type": "object", "properties": { "file": { "type": "string" }, "sha256": { "type": "string" }, "url": { "type": "string" } } }, "reproduce": { "type": "string", "description": "the command that reproduces this verdict without the API" } } }, "example": { "verdict": "VALID", "statementHash": "0x0e937d67740e2314dfa003848dc46600bf6086d3449097f5eb222665c75a4e32", "levels": [ { "level": "form", "state": "PASSED", "detail": "kind=aere-proof-of-payment-attestation" }, { "level": "integrity", "state": "PASSED", "detail": "sha256(statement) == statementHash (0x0e937d67740e2314..)" }, { "level": "signature", "state": "ABSENT", "detail": "the envelope carries no signature" }, { "level": "finality", "state": "ABSENT", "detail": "no notarization claimed and no --rpc given" } ], "verifier": { "file": "verify-proof.mjs", "sha256": "…", "url": "https://aere.network/tools/verify-proof.mjs" }, "reproduce": "node verify-proof.mjs envelope.json --json" } } } }, "400": { "description": "bad_envelope (the body is not one JSON object) or unknown_chain", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/e401" }, "403": { "$ref": "#/components/responses/e403" }, "413": { "description": "envelope_too_large (over 64 KB)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "busy: verifications in flight are capped (Retry-After), or over the plan's per-second limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "verifier_inconsistent (the verifier's verdict and exit code disagree; never passed on as a verdict) or verifier_no_verdict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "verifier_missing / verifier_runtime_missing, or the subscription could not be verified on-chain", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "verifier_timeout (not INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/identity/verify": { "post": { "summary": "Verify an AERE Identity presentation (post-quantum credential with selective disclosure, holder binding, delegation, revocation); VALID / PARTIAL / INVALID, judged by the published command line identity-cli.mjs verify", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "presentation", "audience", "nonce" ], "properties": { "presentation": { "type": "object", "description": "an aere-presentation (the file identity-cli.mjs present writes)" }, "audience": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._~:/?#@!$&'()*+,;=%-]{0,255}$", "description": "your verifier's identifier; the presentation must have been made for it" }, "nonce": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._~:/?#@!$&'()*+,;=%-]{0,255}$", "description": "the challenge you gave the holder" }, "statusLists": { "type": "array", "maxItems": 8, "items": { "type": "object" }, "description": "the issuers' current status lists" }, "revocations": { "type": "array", "maxItems": 32, "items": { "type": "object" }, "description": "revocations of delegation links" }, "trustedIssuers": { "type": "array", "minItems": 1, "maxItems": 32, "items": { "oneOf": [ { "type": "string", "pattern": "^aere-id:[0-9a-f]{40}$" }, { "type": "object" } ] }, "description": "issuer ids or public keys; without them the issuer is not judged (PARTIAL)" }, "maxAgeSeconds": { "type": "integer", "minimum": 1, "maximum": 3600, "default": 300 } } } } } }, "responses": { "200": { "description": "INVALID: a row failed; PARTIAL: every judged row held but some could not be judged (pass: null), so read the verdict; VALID: everything judged and held. claims and subject only when no row failed. reproduce carries the moment of the judgment (--at).", "content": { "application/json": { "schema": { "type": "object", "properties": { "verdict": { "enum": [ "VALID", "PARTIAL", "INVALID" ] }, "notJudged": { "type": "integer" }, "subject": { "type": [ "object", "null" ], "properties": { "type": { "type": "string" }, "credential": { "type": "string" }, "issuer": { "type": "string" }, "holder": { "type": "string" }, "presenter": { "type": "string" }, "delegations": { "type": "integer" } } }, "claims": { "type": [ "object", "null" ] }, "rows": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "pass": { "type": [ "boolean", "null" ] }, "detail": { "type": "string" } } } }, "judgedAt": { "type": "string" }, "verifier": { "type": "object", "properties": { "tool": { "type": "string" }, "sha256": { "type": "object", "additionalProperties": { "type": "string" } }, "source": { "type": "string" } } }, "reproduce": { "type": "string" } } } } } }, "400": { "description": "bad_request, unknown_field, too_deep (nested beyond 64 levels) or rejected_input (the tool's own reason)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "detail": { "type": "string" } } } } } }, "401": { "$ref": "#/components/responses/e401" }, "403": { "$ref": "#/components/responses/e403" }, "413": { "description": "body_too_large (256 KB)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "detail": { "type": "string" } } } } } }, "429": { "description": "busy or busy_account: verifications in flight are capped overall and per account (shared with /verify); Retry-After", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "detail": { "type": "string" } } } } } }, "502": { "description": "verifier_inconsistent or verifier_no_verdict (never passed on as a verdict)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "detail": { "type": "string" } } } } } }, "503": { "description": "identity_verifier_missing or verifier_runtime_missing", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "detail": { "type": "string" } } } } } }, "504": { "description": "verifier_timeout (not INVALID)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "detail": { "type": "string" } } } } } } } } }, "/compliance/check": { "post": { "summary": "Judge a compliance policy on an AERE Identity presentation; COMPLIANT / NOT_COMPLIANT with reasons and, on request, the record as an AIP-23 compliance envelope without personal data", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "presentation", "policy", "audience", "nonce" ], "properties": { "presentation": { "type": "object", "description": "an aere-presentation (the file identity-cli.mjs present writes)" }, "audience": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._~:/?#@!$&'()*+,;=%-]{0,255}$", "description": "your verifier's identifier; the presentation must have been made for it" }, "nonce": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._~:/?#@!$&'()*+,;=%-]{0,255}$", "description": "the challenge you gave the holder" }, "statusLists": { "type": "array", "maxItems": 8, "items": { "type": "object" }, "description": "the issuers' current status lists" }, "revocations": { "type": "array", "maxItems": 32, "items": { "type": "object" }, "description": "revocations of delegation links" }, "policy": { "type": "object", "description": "{ id, trustedIssuers:[id|public key], requireStatus?, maxAgeS?, require:[{ claim, equals|in|notIn|atLeast|present }] }; unknown fields refused; hashed in normal form" }, "record": { "type": "boolean", "default": false } } } } } }, "responses": { "200": { "description": "The policy judged; no claims in the answer.", "content": { "application/json": { "schema": { "type": "object", "properties": { "verdict": { "enum": [ "COMPLIANT", "NOT_COMPLIANT" ] }, "compliant": { "type": "boolean" }, "reasons": { "type": "array", "items": { "type": "string" } }, "policyId": { "type": "string" }, "policyHash": { "type": "string" }, "presentationHash": { "type": "string" }, "notJudged": { "type": "integer" }, "record": { "type": "object", "description": "present with record: true; an AIP-23 envelope (kind aere-proof-of-compliance-attestation) to keep or notarize" }, "judgedAt": { "type": "string" }, "verifier": { "type": "object", "properties": { "tool": { "type": "string" }, "sha256": { "type": "object", "additionalProperties": { "type": "string" } }, "source": { "type": "string" } } }, "reproduce": { "type": "string" } } } } } }, "400": { "description": "bad_request, unknown_field, too_deep (nested beyond 64 levels) or rejected_input (the tool's own reason)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "detail": { "type": "string" } } } } } }, "401": { "$ref": "#/components/responses/e401" }, "403": { "$ref": "#/components/responses/e403" }, "413": { "description": "body_too_large (256 KB)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "detail": { "type": "string" } } } } } }, "429": { "description": "busy or busy_account: verifications in flight are capped overall and per account (shared with /verify); Retry-After", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "detail": { "type": "string" } } } } } }, "502": { "description": "verifier_inconsistent or verifier_no_verdict (never passed on as a verdict)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "detail": { "type": "string" } } } } } }, "503": { "description": "identity_verifier_missing or verifier_runtime_missing", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "detail": { "type": "string" } } } } } }, "504": { "description": "verifier_timeout (not INVALID)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "detail": { "type": "string" } } } } } } } } }, "/identity/sd-jwt/verify": { "post": { "summary": "Verify a standard SD-JWT with key binding (IETF RFC 9901, sections 7.1 and 7.3) against the issuer key you give; VALID / INVALID with the reason and the processed payload", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "sdJwt", "issuerKey", "audience", "nonce" ], "properties": { "sdJwt": { "type": "string", "pattern": "^[A-Za-z0-9_.~-]+$", "description": "SD-JWT+KB in compact serialization" }, "issuerKey": { "type": "object", "description": "the issuer public key: a JWK (EC P-256, OKP Ed25519, AKP ML-DSA-65) or the public keys of an AERE identity" }, "issuerAlg": { "enum": [ "EdDSA", "ES256", "ML-DSA-65" ], "default": "EdDSA" }, "audience": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._~:/?#@!$&'()*+,;=%-]{0,255}$", "description": "your verifier's identifier; the key binding must name it" }, "nonce": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._~:/?#@!$&'()*+,;=%-]{0,255}$", "description": "the challenge you gave the holder" }, "expectedIssuer": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._~:/?#@!$&'()*+,;=%-]{0,255}$", "description": "the iss you expect" }, "maxAgeSeconds": { "type": "integer", "minimum": 1, "maximum": 3600, "default": 300 } } } } } }, "responses": { "200": { "description": "VALID or INVALID with the reason; payload (the processed SD-JWT payload) only when valid.", "content": { "application/json": { "schema": { "type": "object", "properties": { "verdict": { "enum": [ "VALID", "INVALID" ] }, "reason": { "type": "string" }, "payload": { "type": [ "object", "null" ] }, "disclosed": { "type": "array", "items": { "type": "string" } }, "issuer": { "type": [ "string", "null" ] }, "issuerChecked": { "type": "boolean" }, "keyBinding": { "type": [ "object", "null" ] }, "alg": { "type": [ "string", "null" ] }, "judgedAt": { "type": "string" }, "verifier": { "type": "object", "properties": { "tool": { "type": "string" }, "sha256": { "type": "object", "additionalProperties": { "type": "string" } }, "source": { "type": "string" } } }, "reproduce": { "type": "string" } } } } } }, "400": { "description": "bad_request, unknown_field, too_deep (nested beyond 64 levels) or rejected_input (the tool's own reason)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "detail": { "type": "string" } } } } } }, "401": { "$ref": "#/components/responses/e401" }, "403": { "$ref": "#/components/responses/e403" }, "413": { "description": "body_too_large (256 KB)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "detail": { "type": "string" } } } } } }, "429": { "description": "busy or busy_account: verifications in flight are capped overall and per account (shared with /verify); Retry-After", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "detail": { "type": "string" } } } } } }, "502": { "description": "verifier_inconsistent or verifier_no_verdict (never passed on as a verdict)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "detail": { "type": "string" } } } } } }, "503": { "description": "identity_verifier_missing or verifier_runtime_missing", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "detail": { "type": "string" } } } } } }, "504": { "description": "verifier_timeout (not INVALID)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "detail": { "type": "string" } } } } } } } } } } }