Content assertions and lineage
Download this .livemd file, open it in Livebook, and choose
Open → Import from file, then Run all. Use Elixir 1.18 or later and OTP 27 or later
with access to public Hex. No secrets or external services are needed.
Hash exact document bytes, verify two signed generations, and check their pairwise lineage. Refuse changed content, expiry, reversed lineage, and another profile.
The host chooses trusted attestors, content semantics, and the semantic profile digest. Pairwise consistency does not establish the latest generation: durable high-water state, current trust, and replay handling stay with the host. No processes or files are created.
Open this 1.1.0 release notebook. The launch opens this journey at its immutable release tag.
Setup
Install the exact published package. Fixed evaluation times keep the results reproducible; only safe semantic values are persisted, never keys, signatures, tokens, or nonces.
Mix.install([{:bounded_authority_protocol, "== 1.1.0"}])
:ok
Generate the content attestor key
This standalone profile needs one attestor key, not a grant or holder proof. Keep its private half outside all protocol calls.
alias BoundedAuthorityProtocol.ContentAssertion.V1, as: ContentAssertionV1
alias BoundedAuthorityProtocol.V1.HistoricalPublicKey
{content_attestor_public, content_attestor_private} = :crypto.generate_key(:eddsa, :ed25519)
now = 1_800_001_000
:attestor_ready
:attestor_ready
Hash exact content and pin the profile
The content digest includes every supplied byte. The separate semantic-profile digest pins the schema the host selected; the package neither fetches nor interprets that schema.
content_bytes = ~s({"document":"example","revision":1})
{:ok, content_digest} = ContentAssertionV1.content_digest(content_bytes, %{})
# The semantic profile's identity is a caller-pinned opaque 32-byte digest:
profile_digest = :crypto.hash(:sha256, "urn:example:profile:document/1 schema bytes")
%{
content_digest_bytes: byte_size(content_digest),
profile_digest_bytes: byte_size(profile_digest)
}
%{content_digest_bytes: 32, profile_digest_bytes: 32}
Build and sign generation one
Generation one uses the all-zero predecessor digest. Its signed context binds issuer, audience, lineage subject, profile, content digest, and validity window.
assertion = %ContentAssertionV1.ContentAssertion{
attestor_key_id: "content-attestor-1",
jti: "urn:example:assertion:2026-001",
iss: "urn:example:issuer",
aud: "urn:example:audience",
sub: "urn:example:lineage:document-1",
profile: "urn:example:profile:document/1",
profile_digest: profile_digest,
content_digest: content_digest,
gen: 1,
prev: <<0::256>>,
iat: now,
nbf: now,
exp: now + 3_600
}
{:ok, assertion_input} = ContentAssertionV1.assertion_signing_input(assertion, %{})
assertion_signature =
:crypto.sign(:eddsa, :none, assertion_input.message, [content_attestor_private, :ed25519])
{:ok, assertion_compact} =
ContentAssertionV1.assemble_compact(assertion_input, assertion_signature)
:generation_one_signed
:generation_one_signed
Verify generation one
Supply the expected content digest and context from host-owned inputs. The attestor validity window must contain the whole assertion window.
expected_assertion = %ContentAssertionV1.ExpectedContentAssertion{
attestor: %HistoricalPublicKey{
key_id: "content-attestor-1",
public_key: content_attestor_public,
valid_from: now - 600,
valid_before: now + 7_200
},
issuer: "urn:example:issuer",
audience: "urn:example:audience",
subject: "urn:example:lineage:document-1",
profile: "urn:example:profile:document/1",
profile_digest: profile_digest,
content_digest: content_digest,
now: now + 60,
bounds: %{}
}
{:ok, assertion_facts} =
ContentAssertionV1.verify_assertion(assertion_compact, expected_assertion)
Map.take(assertion_facts, [:attestor_key_id, :sub, :gen, :verification, :trust])
%{attestor_key_id: "content-attestor-1", sub: "urn:example:lineage:document-1", gen: 1, verification: :signature_and_window, trust: :not_evaluated}
Build and sign generation two
Hash the revised document and name generation one by the digest of its exact signed compact bytes. A changed document requires its own expected content digest.
successor_bytes = ~s({"document":"example","revision":2})
{:ok, successor_digest} = ContentAssertionV1.content_digest(successor_bytes, %{})
successor = %{
assertion
| jti: "urn:example:assertion:2026-002",
gen: 2,
content_digest: successor_digest,
prev: assertion_facts.digest,
iat: now + 120,
nbf: now + 120
}
{:ok, successor_input} = ContentAssertionV1.assertion_signing_input(successor, %{})
successor_signature =
:crypto.sign(:eddsa, :none, successor_input.message, [content_attestor_private, :ed25519])
{:ok, successor_compact} =
ContentAssertionV1.assemble_compact(successor_input, successor_signature)
:generation_two_signed
:generation_two_signed
Verify generation two
Verify the successor signature, revised content digest, and complete context before comparing lineage. Merely decoding a generation would not establish these facts.
{:ok, successor_facts} =
ContentAssertionV1.verify_assertion(successor_compact, %{
expected_assertion
| content_digest: successor_digest,
now: now + 180
})
Map.take(successor_facts, [:sub, :gen, :verification, :trust])
%{sub: "urn:example:lineage:document-1", gen: 2, verification: :signature_and_window, trust: :not_evaluated}
Check the successor relationship
The pairwise check requires the same lineage context, a forward generation, and the exact
predecessor digest. It returns :ok, not a new facts value or an authority decision.
:ok = ContentAssertionV1.verify_successor(assertion_facts, successor_facts, %{})
:ok
Refuse changed content and expiry
A trailing space changes the content digest even if a parser would ignore it. Evaluation exactly at expiry also fails.
{:ok, changed_digest} = ContentAssertionV1.content_digest(content_bytes <> " ", %{})
{:error, :invalid} =
ContentAssertionV1.verify_assertion(assertion_compact, %{
expected_assertion
| content_digest: changed_digest
})
{:error, :invalid} =
ContentAssertionV1.verify_assertion(assertion_compact, %{
expected_assertion
| now: now + 3_600
})
[:changed_content, :expired]
[:changed_content, :expired]
Refuse reversed lineage and cross-profile bytes
Both generations were verified, but their order cannot be reversed. A content assertion also cannot be decoded as a role attestation or a grant.
{:error, :invalid} = ContentAssertionV1.verify_successor(successor_facts, assertion_facts, %{})
{:error, :invalid} =
BoundedAuthorityProtocol.RoleAttestation.V1.decode_attestation(assertion_compact, %{})
{:error, :invalid} = BoundedAuthorityProtocol.V1.decode_grant(assertion_compact, %{})
[:reversed_lineage, :role_profile, :grant_profile]
[:reversed_lineage, :role_profile, :grant_profile]
See operations for durable lineage state. An assertion proves a trusted key signed the expected bytes and context; it does not prove the content is true.