Upgrading to 1.0

Copy Markdown View Source

Package 1.0.0 is the first release under the 1.x stability contract: from here on, anything that would break your code waits for 2.0.0, with two exceptions a minor release may carry. A soundness repair can reject inputs that no conforming producer emits, and a raised Elixir or Erlang/OTP floor is announced in the changelog (API stability and versioning). This page lists what changes when you move from a 0.x release to 1.0, then the extra steps for older starting points. The changelog has the full history.

Move the requirement

defp deps do
  [{:bounded_authority_protocol, "~> 1.0"}]
end

~> 1.0 admits every 1.x release. A 0.x requirement such as ~> 0.9.1 never selects 1.0, so the change is explicit. Then run mix deps.update bounded_authority_protocol and the packaged corpora (Recipes).

What changes in 1.0

No wire byte changes, and every certified corpus keeps its cases and verdicts. These changes can affect your code:

  1. Float zero in selectors (erratum 6). On every contract-major, grant decode and verification reject a grant whose equals value or one_of member holds a float-tagged zero (0.0, -0.0, or an underflowing literal), and the grant producers refuse a float-tagged whole-number selector value such as {:float, 2.0}. Conforming verifiers disagreed about these values, and no conforming producer emits them. Action: tag whole numbers {:integer, n} in selectors. If you stored grants you did not produce with this package, decode them once; one that no longer decodes held such a value and must be re-issued. See the errata registry.
  2. Conformance internals are hidden. BoundedAuthorityProtocol.Conformance.Corpus, Runner, and Report are no longer documented or covered by the stability contract. Action: call BoundedAuthorityProtocol.Conformance.Cli.run/1, which returns the exit status (0, 1, or 2), or run the bounded_authority_conformance command. Do not call Conformance.Cli.Main.main/1; it halts the VM.
  3. The conformance CLI is stricter. It reads only the files a corpus index names, refuses symbolic links and over-size files, checks that it ran every case the certified index lists exactly once, verifies the three sibling-profile corpora (local-loopback, role attestation, content assertion), exits 0 on --help, writes one line to standard error on a failure, and ends its report with a newline. Its flags, exit statuses, and report fields are now part of the stability contract.
  4. Bounds fields default to the maxima. %Bounds{} equals Bounds.maximum(), and %Bounds{depth: 8} is a one-field tightening. Code that built the struct with every field still works; new/1, maximum/0, and coerce/1 are unchanged.
  5. inspect/2 redacts credentials. Inspecting Credentials, ExpectedRequest, proofs, decoded proofs, or a SigningInput shows :redacted in place of the compact credentials, the cast arguments, the nonce, and the signing bytes. If your tests matched on inspected output, match on the fields instead. Redaction protects against accidental logging only; reading a field still returns its value.
  6. The thumbprint helpers are documented. V1.Jwk.public_key_thumbprint_raw/2, V1.Jwk.thumbprint_raw/2, V3.EcJwk.public_key_thumbprint_raw/2, and V3.EcJwk.thumbprint_raw/2 are now part of the stable surface. Code that already used them needs no change.
  7. The request-digest projection is bounded while it walks. request_digest/3, proof_signing_input/2, and check_envelope/2 stop at the depth, node, container, and string budgets as they project the arguments, instead of after. The accepted set and every digest byte are unchanged; an oversized argument tree is rejected without being walked.

Every public function now has a typespec and every public struct documents its fields, which helps Dialyzer and your editor but changes no behavior.

From older releases

Apply every row from your starting release down to 1.0.

You are onAlso do this
0.8.xES256 compact assembly refuses a high-S or out-of-range signature. If you sign through a KMS or an HSM and assemble yourself, convert with Es256.der_to_raw/1, then Es256.normalize_low_s/1, before assemble_compact/2 (Recipes).
0.7.x or earlierEvery Ed25519 verification applies the strict rule: canonical encodings, no small-order key or R, S below the group order. Before upgrading, run Ed25519.acceptable_public_key?/1 and Ed25519.torsion_free?/1 over every stored trusted key, enrolled holder key, attestation key, and archived key chain, and treat a failure as a compromise. From then on, call torsion_free?/1 at enrollment, at trust install, and before revocation comparisons. Producers refuse a placeholder key such as 32 zero bytes. These releases are retired on Hex.

Checking that you are unaffected

  1. Move the requirement and keep mix.lock committed, so the exact release is recorded.
  2. Run every packaged corpus from your project (Recipes). Exit 0 for each means the installed release agrees with every certified corpus.
  3. If your own tests pin a corpus index digest, it does not change in 1.0.
  4. Run your integration tests, including the rejection paths, and fix any test that matched on inspect/2 output.

After 1.0

Read the changelog's entry for each minor release you adopt. A minor release may add a contract-major, a sibling profile, functions, optional arguments, defaulted struct fields, or a soundness repair recorded in the errata registry, and may raise the Elixir or Erlang/OTP floor; none requires a code change. A 2.0.0 release would say what to change.