AlphaAssay certificate and trust specification

July 27, 2026 ยท View on GitHub

This document defines the language-independent offline verification contract. It separates raw cryptographic evidence from AlphaAssay platform trust.

Certificate artifact

A certificate is one strict JSON object accompanied by an Ed25519 signature over its canonical bytes. The payload includes a certificate_id; cert1 payload fields such as the disclaimer and engine version are covered by the same signature.

Canonical JSON

The fixed identifier is json-sort-keys-ascii-nospace-nfc-float12:

  1. Object keys are sorted lexicographically.
  2. Output is ASCII; non-ASCII characters use JSON escapes.
  3. Separators are , and : with no insignificant whitespace.
  4. NaN and Infinity are rejected.
  5. An integral float is emitted as an integer; other floats are rounded to twelve decimal places.
  6. Strings and object keys normalize to Unicode NFC.
  7. Non-JSON values are rejected.

Signed-artifact validation is stricter than normalization: raw duplicate keys, NFC-colliding or non-NFC keys, non-string in-memory keys, cycles, and unsupported node types are rejected. Container depths 0 through 63 are admissible; a container at depth 64 is rejected.

The canonical bytes are the UTF-8 encoding of the canonical string. Conforming implementations reproduce tests/canonical_vectors.json.

Public-key identity

Only one strict Ed25519 SubjectPublicKeyInfo PEM object is accepted. CRLF and LF input produce the same canonical PEM. Concatenated/trailing PEM objects and other key types are rejected.

For canonical SPKI PEM:

spki_sha256 = lowercase_hex(SHA-256(canonical_spki_pem_bytes))
key_id      = "key_" + first_16_hex(spki_sha256)

The truncated key_id is retained for compatibility and revocation matching. Security anchoring and identity uniqueness use the complete 64-hex spki_sha256.

Raw signature verification

verify_signature(certificate, signature_b64, public_key_pem) and verify_certificate(...) are signature-only APIs. The signature must be canonical standard Base64 and decode to exactly 64 bytes. These APIs prove only that the supplied key signed the strict canonical object; they do not return a platform-trust status.

Signed version-2 trust bundle

The top-level object has exactly:

artifact_type, schema_version, canonicalization, legacy,
entries, heads, trusted_keys, latest_head

artifact_type is alphaassay.revocation_bundle, schema_version is 2, and canonicalization is the fixed identifier above. Unknown or missing fields at any signed schema level are invalid.

Revocation entries

Entries are ordered from sequence 1 and contain exactly:

sequence, scope, match_value, reason, revoked_at,
predecessor_entry_hash, legacy_line_hash, entry_hash

scope is one of certificate_id, engine_version, or key_id. Each entry_hash is the canonical SHA-256 of the entry without entry_hash, and predecessor_entry_hash links to the preceding entry.

Signed heads

Each head contains exactly payload, keyring, signature_b64, and head_hash. Its payload identifies the artifact/schema/purpose, sequence, entry count and terminal entry hash, predecessor head, signer key identity, keyring and legacy digests, and timestamp.

The head signature covers the canonical payload. The head hash covers the complete head except head_hash. Head sequence, entry coverage, and time are monotonic; every digest and predecessor link must match.

Keyring lifecycle

Key records contain exactly:

key_id, spki_sha256, key_type, public_key_pem, purposes, status

Purposes are selected from certificate, calibration_snapshot, and trust_head. The keyring is sorted by full fingerprint and cannot contain duplicate full fingerprints or compatible IDs.

A successor head signer must have been an active trust_head key in the predecessor's signed keyring. Certificate and calibration keys are retained in successor keyrings. A key may transition from active to retired, never back to active. A retired retained certificate key still verifies its historical certificate.

External root and checkpoints

A bundle never self-roots. The genesis signer must be an active trust_head key whose full canonical-SPKI fingerprint appears in the caller's external root-pin set.

A caller may require a minimum signed-head sequence and hash. An unavailable, malformed, or older history fails with revocation_head_unanchored.

Full trusted certificate verification

verify_trusted_certificate() accepts the certificate/signature, an optional public key, the local trust bundle, external root fingerprints, and optional minimum checkpoint.

valid=true is possible only when:

  1. the raw signature is valid;
  2. the complete bundle structure, links, anchor, signatures, transitions, and checkpoint are valid;
  3. exactly one certificate-purpose key in the latest verified keyring matches; and
  4. no certificate-, engine-, or key-ID revocation matches.

If public-key evidence is supplied, it must be the canonical identity recorded in the verified keyring. Without it, exactly one matching historical certificate-purpose key is selected.

A full result always includes:

valid, signature_valid, chain_valid, revocation_chain_valid,
revoked, status, reason, reason_code

A revoked certificate has a valid signature and chain but valid=false, revoked=true, status="valid_but_revoked", and reason_code="certificate_revoked".

Stable reason precedence

Reasons are evaluated in this order:

  1. malformed_public_key or unsupported_key_type
  2. malformed_signature
  3. signature_mismatch (payload is not a strict canonical JSON object)
  4. not_a_certificate (well-formed payload whose schema_version is not cert1 -- a validly signed sibling artifact such as a calibration snapshot or trust head is never accepted as a certificate)
  5. signature_mismatch (Ed25519 verification fails)
  6. revocation_bundle_missing
  7. revocation_entry_malformed
  8. revocation_link_mismatch
  9. revocation_head_unanchored
  10. revocation_head_signature_invalid
  11. unknown_key_id
  12. certificate_revoked
  13. valid

No parsing or verification exception escapes the full verifier.

Legacy JSONL

Unsigned hash-chained JSONL may be inspected through check_revocation() as low-level migration evidence. It is not an authority, cannot anchor a signed bundle, and is never consumed by full trusted verification.

CLI

verify performs full trusted verification from local files and explicit root pins. signature-only is the explicitly raw mode. Neither command fetches keys, bundles, pins, or certificates.