Should CLI/GUI tools expose checksum completion?

[BenWestgate]

Before releasing python-codex32 v1, I’d appreciate feedback on whether checksum completion is useful enough to justify its misuse risk.

My candidate ms32 checksum command completes a Codex32 Book worksheet. It saves manual checksum computation, but can also give wrong data a valid checksum. Users might interpret that as evidence their backup is secure/random.

Safeguards:

• Requires a valid codex32 header and format, and exactly 26, 32, 39, 45, 52, or 103 payload characters. Bad input is rejected without explaining the required format or length.
• Two independent entries must agree. The command clears the screen and scrollback before re-entry, without showing the previous answer. Automatic input history is disabled.
• No result or hint about what should have been entered is given after invalid input, a mismatch, or cancellation.
• Help and prompts deliberately give no input recipe: no explanation of header fields, length, or character set. Users are referred to the Book.

These checks cannot guarantee data was generated correctly. Entering wrong data twice can still succeed.

Help

Complete a Codex32 Book checksum worksheet.
Requires an interactive terminal and two matching entries.

Proposed warning

DANGER: Incorrect input can cause permanent loss of funds.
Follow the Codex32 Book procedure and its Dice De-biasing Worksheet exactly.
This command cannot verify how your data was generated.
Do not enter raw dice rolls, seed words, hexadecimal seeds, or passwords.

Prompts, separated by terminal clearing

Checksum worksheet non-pink bold squares:

> MS1

Re-enter the worksheet non-pink bold squares:

> MS1

Input errors

ms32 checksum: The input does not match the expected format of the filled-out non-pink bold squares.
Consult the Codex32 Book and check the worksheet.

ms32 checksum: No input was provided.

Would you keep this command or remove user-facing checksum completion? What about for a GUI? My concern is users may checksum low entropy data or replace a damaged backup’s checksum.

[BenWestgate]

Slightly related,ms32 correct produces a warning when less than 5-bits of checksum discrimination remain for the candidate. That includes 13 or 15 contiguous erasures and possibly some other correction classes. I refuse to show corrections that exceed the checksums' discrimination i.e. 14/16 erasures.

This is because filling erasures is effectively the checksum command. But it's also important users know the correction is unreliable as it has BIP39 levels of error detection left.

[apoelstra]

My concern is users may checksum low entropy data or replace a damaged backup’s checksum.

Yeah. So, if they're starting with low entropy data there's not too much we can do. But I don't think users will be fooled into thinking that the checksum somehow makes "insecure data" into "secure data".

I do think users will be fooled into thinking that they can take data with poor integrity (or data which is actually wrong/corrupted) and then "restore it" by using the checksum generation. I agree it seems plausible that users would drop a checksum that doesn't validate then attempt to "restore it".

So my proposal is:

• Keep your angry red warnings when the user tries to correct something with too many errors/erasures.
• Drop an explicit "checksum completer" but maybe suggest to users somewhere that they can do the same thing by just putting 13 erasures at the end of their data (and then the existing warning will yell at them). If we make this suggestion we should emphasize that users should NOT attempt to delete and replace a checksum on existing data, since this will only "lock in" the actual errors.

We should also extend the "are you recovering" warning. I think we should say something like:

If you are generating new data and attempting to fill in the missing squares to complete a checksum,
ensure that you have transcribed the data **exactly as it will be used**. There is no way to detect
or correct transcription errors, so any errors you have made up to this point will be "locked in" by
completing the checksum.

If you are recovering data with this many missing characters, understand that the completion may
be incorrect and you may need to resort to other methods (e.g. grinding through possible typos)
to recover you data.

If you understand this, type YES to attempt to correct the data.