Powered by AppSignal & Oban Pro

Content assertions and lineage

docs/notebooks/content-lineage.livemd

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.