Aeonite

Neutral specifications and test suites for meaning-aware data interchange.

Status: Draft normative v1 appendix

Available formats: HTML, Markdown

Appendix — Integrity Envelope

Appendix to: AEON Specification v1

Status: normative v1 appendix

Canonical topic owner: ../AEON-spec-v1.md

This appendix defines the standard AEON integrity envelope shape used by the baseline security conventions:

  • aeon.gp.security.v1
  • aeon.gp.integrity.v1
  • aeon.gp.signature.v1
  • aeon.gp.encryption.v1

The envelope is optional. If present, it is inert with respect to document meaning. It is modeled as a normal top-level object binding whose datatype is :envelope. Consumers are free to use :envelope the same way they use any other object alias; the GP security conventions simply reserve a conventional role for it.

1. Purpose

The integrity envelope provides a standard location for:

  • canonical integrity hashes
  • signatures over those hashes
  • optional encrypted payload metadata

It MUST NOT alter document meaning, evaluation, profile selection, schema selection, or reference legality.

2. Declaration and Conventions

Documents using the standard security envelope should declare the relevant conventions in aeon:header.

Example:

Convention declarations remain advisory until trusted or selected by the consumer.

3. Envelope Declaration

The standard envelope is declared as a typed top-level binding. close is the recommended conventional key, but it is not semantically privileged by Core:

The envelope object may contain the following standard sections:

  • integrity
  • signatures
  • encryption

Additional sections are convention-defined and non-Core.

4. Placement Rules

  1. The chosen top-level :envelope binding MUST be the final binding in the document.
  2. Only whitespace or comments may follow it.
  3. The envelope is excluded from integrity-hash coverage.

5. Standard Sections

5.1 integrity

Defined by aeon.gp.integrity.v1.

Field Required Meaning
alg yes canonical hash algorithm
hash yes canonical hash over the envelope-free document body

5.2 signatures

Defined by aeon.gp.signature.v1.

Field Required Meaning
alg yes signature algorithm
kid yes key identifier
sig yes signature bytes/text form

5.3 encryption

Defined by aeon.gp.encryption.v1.

Field Required Meaning
alg yes encryption algorithm
kid yes recipient or key identifier
ciphertext yes encrypted payload representation

6. Excluded Content

The standard envelope does not authorize:

  • schema or profile selection
  • processor enablement
  • trust-model self-assertion
  • embedded public-key trust
  • executable behavior

These remain consumer-policy concerns.

7. Canonical Integrity Coverage

7.1 Coverage Rule

The canonical integrity hash is computed over the document body excluding the top-level :envelope binding.

7.2 Input Model

Canonical hashing derives from the Assignment Event stream:

  1. compile the document body to AES
  2. exclude the selected top-level :envelope subtree (for example $.close)
  3. serialize the resulting canonical state deterministically
  4. hash that serialization using the declared integrity algorithm

7.3 Coverage Notes

  • the envelope is never included in its own integrity hash
  • comments and annotation records are not part of canonical integrity coverage
  • convention declarations in aeon:header are covered because they are part of the body state

8. Signature Coverage

Standard signatures are computed over the integrity hash declared in the selected envelope binding's integrity section.

This means:

  1. compute the canonical integrity hash
  2. sign that hash representation
  3. store the result in the envelope binding's signatures

Public keys are resolved out-of-band by consumer policy. Implementations MUST NOT trust embedded key material by default.

9. Verification Procedure

  1. Parse the document structurally.
  2. Confirm the top-level :envelope binding, if present, is the final binding.
  3. Read aeon:header.conventions if present, but treat them as advisory.
  4. Recompute the integrity hash over the envelope-free document body.
  5. Compare the result with the envelope binding's integrity.hash.
  6. If signatures are present, verify them against trusted external key material.
  7. If encryption metadata is present, apply separate consumer policy for decryption.

10. Security Notes

  • Integrity hashes provide tamper evidence, not trust by themselves.
  • Signature verification depends on trusted key resolution.
  • Encryption metadata does not itself imply confidentiality unless the consumer recognizes and applies the corresponding convention.
  • The envelope MUST NOT influence schema/profile selection.

11. Minimal Full Example

End of Integrity Envelope