Powered by AppSignal & Oban Pro

Role attestations

docs/notebooks/role-attestations.livemd

Role attestations

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.

Bind a subject public key to an issuer role. Verify its attestor window and subject binding, then refuse self-attestation, expiry, an overlong window, and cross-profile bytes.

The host chooses the attestor it trusts and the role it requires. Attestation facts report trust: :not_evaluated; they do not grant authority or reserve replay. Keys stay in memory, and this notebook starts no processes and creates no files.

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 attestor and subject keys

Generate distinct Ed25519 keys for the attestor and subject. A role binding needs no grant or request proof.

alias BoundedAuthorityProtocol.RoleAttestation.V1, as: RoleAttestationV1
alias BoundedAuthorityProtocol.V1.HistoricalPublicKey

{attestor_public, attestor_private} = :crypto.generate_key(:eddsa, :ed25519)
{subject_public, _subject_private} = :crypto.generate_key(:eddsa, :ed25519)

now = 1_800_001_000
:keys_ready
:keys_ready

Build and sign the attestation

The attestor signs a standalone ba+role-attestation JWS. Its payload names the subject key, role, identifier, and validity window.

attestation = %RoleAttestationV1.RoleAttestation{
  attestor_key_id: "authority-attestor-1",
  jti: "urn:example:attestation:2026-001",
  key_id: "issuer-key-1",
  public_key: subject_public,
  role: "issuer",
  nbf: now,
  exp: now + 3_600
}

{:ok, attestation_input} = RoleAttestationV1.attestation_signing_input(attestation, %{})

attestation_signature =
  :crypto.sign(:eddsa, :none, attestation_input.message, [attestor_private, :ed25519])

{:ok, attestation_compact} =
  RoleAttestationV1.assemble_compact(attestation_input, attestation_signature)

:attestation_signed
:attestation_signed

Verify the subject binding and window

Supply the expected subject independently and an already-trusted historical attestor key. The attestation window must fit entirely inside that key window.

expected_attestation = %RoleAttestationV1.ExpectedAttestation{
  attestor: %HistoricalPublicKey{
    key_id: "authority-attestor-1",
    public_key: attestor_public,
    valid_from: now - 600,
    valid_before: now + 7_200
  },
  subject_key_id: "issuer-key-1",
  subject_public_key: subject_public,
  now: now + 60,
  bounds: %{}
}

{:ok, attestation_facts} =
  RoleAttestationV1.verify_attestation(attestation_compact, expected_attestation)

Map.take(attestation_facts, [:attestor_key_id, :subject_key_id, :role, :trust])
%{attestor_key_id: "authority-attestor-1", subject_key_id: "issuer-key-1", role: "issuer", trust: :not_evaluated}

Refuse a true self-attestation

Sign a binding to the attestor itself and make the expected subject match. The refusal then comes from the structural self-attestation rule, rather than a subject mismatch.

# A true self-attestation: the payload binds the attestor's own key id and key material, and
# the expected subject matches it, so every binding check passes and only the structural
# self-attestation rejection can fire.
self_attestation = %{attestation | key_id: "authority-attestor-1", public_key: attestor_public}

{:ok, self_input} = RoleAttestationV1.attestation_signing_input(self_attestation, %{})
self_signature = :crypto.sign(:eddsa, :none, self_input.message, [attestor_private, :ed25519])
{:ok, self_compact} = RoleAttestationV1.assemble_compact(self_input, self_signature)

{:error, :invalid} =
  RoleAttestationV1.verify_attestation(self_compact, %{
    expected_attestation
    | subject_key_id: "authority-attestor-1",
      subject_public_key: attestor_public
  })
{:error, :invalid}

Refuse expired or outliving attestations

The acceptance interval is half-open: evaluation at exp fails. An otherwise current attestation also fails when it outlives its attestor key.

{:error, :invalid} =
  RoleAttestationV1.verify_attestation(attestation_compact, %{
    expected_attestation
    | now: now + 3_600
  })

{:error, :invalid} =
  RoleAttestationV1.verify_attestation(attestation_compact, %{
    expected_attestation
    | attestor: %{expected_attestation.attestor | valid_before: now + 1_800}
  })

[:expired, :outliving_attestor]
[:expired, :outliving_attestor]

Refuse a different subject

A signature from a trusted attestor does not permit substituting a subject. The expected key id and public key both bind the statement to the subject the host intended.

{:error, :invalid} =
  RoleAttestationV1.verify_attestation(attestation_compact, %{
    expected_attestation
    | subject_key_id: "other-subject"
  })

{:error, :invalid} =
  RoleAttestationV1.verify_attestation(attestation_compact, %{
    expected_attestation
    | subject_public_key: attestor_public
  })

[:subject_key_id, :subject_public_key]
[:subject_key_id, :subject_public_key]

Refuse cross-profile decoding

These bytes decode as a role attestation but never as a grant or content assertion. Selecting a profile remains an explicit host choice.

{:ok, _decoded} = RoleAttestationV1.decode_attestation(attestation_compact, %{})
{:error, :invalid} = BoundedAuthorityProtocol.V1.decode_grant(attestation_compact, %{})

{:error, :invalid} =
  BoundedAuthorityProtocol.ContentAssertion.V1.decode_assertion(attestation_compact, %{})

[:grant_profile, :content_profile]
[:grant_profile, :content_profile]

See trusted keys and rotation for trust installation and the role-attestation specification for the profile.