Core envelope verification
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.
Build a contract-major 1 grant and holder proof for reading a record, verify their request binding, and refuse changed bytes, disallowed arguments, and stale proofs.
The host supplies trusted issuer keys and request context. Verification produces facts, not execution authority; revocation, replay reservation, and the final decision belong to the host. Demonstration keys stay in memory. 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 issuer and holder keys
Generate two independent Ed25519 keys. The grant identifies its holder by the raw RFC 7638 thumbprint, not by private key material.
{issuer_public, issuer_private} = :crypto.generate_key(:eddsa, :ed25519)
{holder_public, holder_private} = :crypto.generate_key(:eddsa, :ed25519)
{:ok, holder_thumbprint} =
BoundedAuthorityProtocol.V1.Jwk.public_key_thumbprint_raw(holder_public, %{})
{byte_size(issuer_public), byte_size(holder_thumbprint)}
{32, 32}
Build and sign the grant
The issuer permits one operation under conjunctive selectors. Sign the exact JWS input with
:crypto; the protocol producer receives only the resulting signature.
alias BoundedAuthorityProtocol.V1.{Grant, Operation}
grant = %Grant{
key_id: "issuer-1",
issuer: "https://issuer.example",
grant_id: "grant-2026-001",
audiences: ["https://service.example"],
issued_at: 1_800_000_000,
not_before: 1_800_000_000,
expires_at: 1_800_003_600,
holder_thumbprint: holder_thumbprint,
operations: [
%Operation{
name: "read_record",
selectors: [
{:equals, ["record", "region"], {:string, "us-east"}},
{:one_of, ["record", "tier"], [{:string, "gold"}, {:string, "platinum"}]},
:all
]
}
]
}
{:ok, signing_input} = BoundedAuthorityProtocol.V1.grant_signing_input(grant, %{})
issuer_signature = :crypto.sign(:eddsa, :none, signing_input.message, [issuer_private, :ed25519])
{:ok, grant_compact} =
BoundedAuthorityProtocol.V1.assemble_compact(signing_input, issuer_signature)
:grant_signed
:grant_signed
Build and sign the holder proof
Bind the exact grant compact bytes, method, target, invocation, operation, and tagged arguments. The holder signs this input with the key the grant names.
alias BoundedAuthorityProtocol.V1.Proof
now = 1_800_001_000
proof = %Proof{
holder_public_key: holder_public,
proof_id: "proof-2026-001",
method: "GET",
target_uri: "https://service.example/records/1",
issued_at: now,
nonce: nil,
invocation_id: "7d444840-9dc0-11ed-a8fc-0242ac120002",
operation: "read_record",
grant_compact: grant_compact,
cast_arguments:
{:object,
[
{"record", {:object, [{"tier", {:string, "gold"}}, {"region", {:string, "us-east"}}]}}
]}
}
{:ok, proof_input} = BoundedAuthorityProtocol.V1.proof_signing_input(proof, %{})
holder_signature = :crypto.sign(:eddsa, :none, proof_input.message, [holder_private, :ed25519])
{:ok, proof_compact} = BoundedAuthorityProtocol.V1.assemble_compact(proof_input, holder_signature)
:proof_signed
:proof_signed
Verify the grant
Supply an already-trusted issuer key, expected audience, and evaluation time. Project only safe identifiers and the explicit non-authorization marker from the returned facts.
alias BoundedAuthorityProtocol.V1.{TrustedIssuer, ExpectedGrant}
trusted = %TrustedIssuer{key_id: "issuer-1", public_key: issuer_public}
expected_grant = %ExpectedGrant{
issuer: "https://issuer.example",
audience: "https://service.example",
evaluation_time: now,
clock_skew: 60,
bounds: %{}
}
{:ok, grant_facts} =
BoundedAuthorityProtocol.V1.verify_grant(grant_compact, trusted, expected_grant)
Map.take(grant_facts, [:issuer, :grant_id, :authorization])
%{issuer: "https://issuer.example", grant_id: "grant-2026-001", authorization: :not_evaluated}
Verify the envelope
Derive the expected request from the host request boundary. Envelope verification rechecks the grant, holder signature, request binding, freshness, and every selector.
alias BoundedAuthorityProtocol.V1.{Credentials, ExpectedRequest}
credentials = %Credentials{grant: grant_compact, proof: proof_compact}
expected_request = %ExpectedRequest{
trusted_issuer: trusted,
issuer: "https://issuer.example",
audience: "https://service.example",
method: "GET",
target_uri: "https://service.example/records/1",
invocation_id: "7d444840-9dc0-11ed-a8fc-0242ac120002",
operation: "read_record",
cast_arguments:
{:object,
[
{"record", {:object, [{"tier", {:string, "gold"}}, {"region", {:string, "us-east"}}]}}
]},
evaluation_time: now,
clock_skew: 60,
proof_max_age: 300,
nonce: :not_required,
bounds: %{}
}
{:ok, envelope_facts} = BoundedAuthorityProtocol.V1.check_envelope(credentials, expected_request)
Map.take(envelope_facts, [:operation, :authorization])
%{operation: "read_record", authorization: :not_evaluated}
Refuse a changed signature
Flip a bit in the decoded signature and re-encode it canonically. The grant fails even though its header and payload are unchanged.
[header, payload, encoded_signature] = String.split(grant_compact, ".")
<<first, rest::binary>> = Base.url_decode64!(encoded_signature, padding: false)
changed_signature = Base.url_encode64(<<Bitwise.bxor(first, 1), rest::binary>>, padding: false)
tampered = Enum.join([header, payload, changed_signature], ".")
{:error, :invalid} =
BoundedAuthorityProtocol.V1.check_envelope(%{credentials | grant: tampered}, expected_request)
{:error, :invalid}
Refuse changed request arguments
A valid proof cannot be reused for a different request body. The signed request digest must match the host-derived tagged arguments.
wrong_arguments =
{:object,
[{"record", {:object, [{"tier", {:string, "bronze"}}, {"region", {:string, "us-east"}}]}}]}
{:error, :invalid} =
BoundedAuthorityProtocol.V1.check_envelope(credentials, %{
expected_request
| cast_arguments: wrong_arguments
})
{:error, :invalid}
Refuse a matching proof outside the selectors
Sign a fresh proof for the disallowed arguments so its request binding is correct. This refusal isolates selector enforcement from the previous digest mismatch.
{:ok, disallowed_input} =
BoundedAuthorityProtocol.V1.proof_signing_input(%{proof | cast_arguments: wrong_arguments}, %{})
disallowed_signature =
:crypto.sign(:eddsa, :none, disallowed_input.message, [holder_private, :ed25519])
{:ok, disallowed_proof} =
BoundedAuthorityProtocol.V1.assemble_compact(disallowed_input, disallowed_signature)
{:error, :invalid} =
BoundedAuthorityProtocol.V1.check_envelope(%{credentials | proof: disallowed_proof}, %{
expected_request
| cast_arguments: wrong_arguments
})
{:error, :invalid}
Refuse a stale proof
The proof is too old after its maximum age plus skew, while the grant is still live. The closed error exposes no details to the caller.
{:error, :invalid} =
BoundedAuthorityProtocol.V1.check_envelope(credentials, %{
expected_request
| evaluation_time: now + 361
})
{:error, :invalid}
Continue with service integration for host-owned trust rotation and replay retention, or troubleshooting for diagnosing refusals.