53 lines
5.4 KiB
Markdown
53 lines
5.4 KiB
Markdown
# proof-kinds: one builder for every AIP-23 proof kind
|
|
|
|
A generic builder of AERE Proof Protocol envelopes (AIP-23) for the standard proof kinds: `data`, `execution`, `identity`,
|
|
`compliance`, `runtime`, `location`, `device`, `payment`, `ownership`, `time`, `block`, `authorization`, `settlement`,
|
|
`provenance`, since 2026-10-18 `secret-access` and since 2026-10-19 `agent-witness-checkpoint`. Every kind produces the same envelope (`statement` plus `statementHash`, the
|
|
SHA-256 of the canonical statement text), so the same AIP-23 reference verifier checks all of them with no kind-specific
|
|
verification code.
|
|
|
|
```
|
|
import { buildProof, KINDS } from './proof-kinds.mjs';
|
|
const envelope = buildProof('runtime', { host, artifactContent, attested, matches: true, createdAt });
|
|
```
|
|
|
|
A kind is a schema: its required fields, some of them digests, plus `createdAt`. Raw content given for a digest field is hashed
|
|
(bytes as they are, strings as UTF-8, other values as their JSON text), and a value that is already a 32-byte digest is kept, so
|
|
an envelope carries digests, never the raw content. A missing required field stops the build with an error instead of producing
|
|
an incomplete envelope. Notarization and the post-quantum certificate over it come from AIP-23, not from this builder.
|
|
|
|
`secret-access` is the audit entry of the secrets service (`pq-secrets/`): the service (its audience), the secret name, the version,
|
|
the operation, the verdict (`allowed`, `refused`, or since 2026-10-18 `failed`: allowed and entered, then the change could not be
|
|
stored) with the rules that refused, the grant that allowed, the holder and the presenter (key-derived `aere-id` identities,
|
|
verified), the digest of the presentation's signed binding (`presentationHash`) and of the grant's policy (`policyHash`). It never
|
|
carries the secret value, nor a digest of it: a digest of a guessable value does not hide it. Since 2026-10-18 (the adversarial
|
|
review of the secrets service) it may also carry `requestHash` (the digest of the request received, already a 32-byte hash),
|
|
`claimedHolder` / `claimedPresenter` (ids a presentation claimed and nobody verified) and `judged` (on a refusal, each grant judged
|
|
with the rules it refused on); envelopes without these fields are byte for byte what they were.
|
|
|
|
`agent-witness-checkpoint` is the checkpoint of the hosted agents witness (`agents/martor-agenti.mjs`), in the form of a transparency log
|
|
checkpoint (C2SP tlog-checkpoint: the log's name, its size, its RFC 9162 root): `root` and `previous` (the statementHash of the checkpoint
|
|
before it, absent on the first) are already 32-byte hashes and are refused in another form; `log`, `witness` (the id derived from the
|
|
witness's ML-DSA-65 key, which signs the envelope), `chainId` (where checkpoints are notarized), `treeSize` and `maxMergeDelay` (seconds
|
|
between receiving a head and covering it with a notarized checkpoint) have a vocabulary (below). The leaves of the tree are digests of the
|
|
signed ledger heads it received, nothing of any ledger.
|
|
|
|
**A kind may have a vocabulary** (`valori` in its schema: per field, a predicate and what it says), judged by `buildProof` on every
|
|
field present; two kinds have one. `secret-access`: `verdict` is `allowed`, `refused` or `failed`, `operation` one of the
|
|
operations of the secrets service (`SECRET_ACCESS.operations`, which the service requires to be its own list), `version` an integer of
|
|
at least 1 or `null`, `rules` a list of rule names, ids `aere-id:` + 40 hex or `null`, `createdAt` an RFC 3339 time. An envelope with
|
|
the verdict `banana` is no longer built. The reference verifier does not judge vocabularies (it judges the form and the hash of any
|
|
kind), so an envelope written by hand with such values stays `VALID` there: the vocabulary is the builder's promise, not the
|
|
verifier's. `agent-witness-checkpoint` (since 2026-10-19, the adversarial review of the hosted witness): `root` and `previous` 0x + 64
|
|
lowercase hex, `log` 1 to 256 printable ASCII characters without spaces, `witness` `aere-witness:` + 40 lowercase hex, `chainId`, `treeSize`
|
|
and `maxMergeDelay` integers of at least 1, `createdAt` an RFC 3339 time; the vocabulary is one exported object (`AGENT_WITNESS_CHECKPOINT`)
|
|
that the witness's own judge of a checkpoint (`verificaPunct` in `agents/martor-agenti.mjs`) imports, so the builder and the judge cannot
|
|
drift apart. Until then a checkpoint with `treeSize` "5" or `maxMergeDelay` 0 was built, and `VALID` at the reference verifier, while the
|
|
witness refused it. `KINDS.json` of the published copy names the values of each field that has them.
|
|
|
|
Test: `node proba-proof-kinds.mjs` (32 checks since 2026-10-19, after the review of the hosted witness: every kind built and found `VALID` by the reference verifier, eight negative
|
|
controls such as content changed after hashing, a required field missing or a `secret-access` value outside its vocabulary, no raw
|
|
content in any envelope, bytes hashed as bytes, the new `secret-access` fields, the two vocabularies held by those two kinds alone, eleven values outside the vocabulary of the witness checkpoint
|
|
refused, and that vocabulary being the very object the witness imports). It needs the AIP-23 reference verifier: `AERE_VERIFY_PROOF=<path to verify-proof.mjs>` (as published at
|
|
aere.network/tools, with `verify-anchor.mjs`, `mpt.mjs`, `falcon512.mjs`, `registry-v3.mjs` and `package.json` beside it and `npm install` done there); without it the test reports that it did not measure and exits with 2. Node.js 24.
|