The envelope that was detected (e.g. 'offcrypto').
The handle being opened — use its name in the prompt.
Tries a password without ending the prompt, so a dialog can report "incorrect password" in place and let the user try again.
true if the password opens the source.
Anything other than a wrong password (a malformed container, an unsupported scheme) — those are not retryable and should surface to the user as errors.
Calling this is optional but strongly preferred: the caller owns the retry loop, and this is what lets it stay in one dialog instead of closing and reopening one per attempt. A prompt that returns a password without validating it is still honored — it simply gets one attempt.
Work is not repeated: a password that validated here is not decrypted a second time when the prompt resolves. Expect the call to take a noticeable moment (the derivation is deliberately expensive) and show a busy affordance rather than freezing the dialog.
The context passed to ReadOptions.onPassword.