@spec binding_aad(String.t(), String.t(), non_neg_integer(), String.t(), integer()) ::
  binary()

Builds deterministic authenticated data for a persisted successor bundle.

Term encoding avoids delimiter ambiguity in host-controlled identifiers. The payload and deadline are also authenticated by the encryption envelope; keeping the binding fields here prevents moving a valid ciphertext to a different parent, family, generation, or child row.

@spec configured?() :: boolean()

Reports whether a usable refresh-successor secret is configured.

This checks only presence and the minimum 32-byte length. Operators must keep the value stable across every node and deployment that can serve the same refresh-token families.

@spec decrypt(binary()) :: {:ok, term()} | :error

Decrypts and safely decodes a refresh-token successor ciphertext.

Authentication failures and missing or invalid configuration return :error, matching the pre-consolidation call sites.

@spec decrypt(binary(), binary()) :: {:ok, term()} | :error

Decrypts a successor using the supplied authenticated-data value.

@spec derive_keys(term()) :: {:ok, binary(), binary()} | :error

Derives the encryption and signing keys from a refresh-successor secret.

Kept public so the exact derivation has direct deterministic coverage.

@spec encrypt(term()) :: {:ok, binary()} | :error

Encrypts a successor term with the configured refresh-successor secret.

Returns :error when the secret is missing or too short. The caller owns the persisted version wrapper around the returned ciphertext.

@spec encrypt(term(), binary()) :: {:ok, binary()} | :error

Encrypts a successor using an explicit authenticated-data value.

The Ecto refresh store uses this form to bind the ciphertext to the parent token hash, family, generations, child hash, and fixed retry deadline. The successor itself remains inside the authenticated ciphertext.