Skip to content

Clarify CLI password prompts and streamline fingerprint enrollment - #62

Open
alsocat wants to merge 1 commit into
mainfrom
cli/enrollment-ux
Open

Clarify CLI password prompts and streamline fingerprint enrollment#62
alsocat wants to merge 1 commit into
mainfrom
cli/enrollment-ux

Conversation

@alsocat

@alsocat alsocat commented Sep 3, 2026

Copy link
Copy Markdown
Collaborator

What changed

CLI-only UX changes in tinytouch. No protocol, firmware, or Keychain behavior is affected.

Password prompts

  • Every password prompt now says Nothing appears as you type — that is normal. Applies to the HID Keychain capture, the HID re-entry path, and the PIV sudo authorization.
  • The PIV path previously fell through to sudo's bare Password:. It now uses sudo -v -p "Mac password: " so both modes read identically, preceded by a short macOS needs to authorize this step. Your password is not saved. — the honest contrast with HID, where the password is stored in the Keychain.

Enrollment

  • Replaced the four full sentences per scan with a Scan N of 4 header and indented touch the sensor / lift your finger / touch again steps, with blank lines between scans.
  • Added a closing Fingerprint enrolled. line.

Audio feedback

  • New chime() helper plays macOS system sounds during enrollment: Tink on each touch prompt, Pop on lift, Glass once all four scans complete.
  • Non-blocking (afplay via Popen), and silently no-ops off macOS, when the sound file is missing, or when TINYTOUCH_NO_SOUND is set.

Why

Setup reads as intimidating to users who aren't comfortable in a terminal. Hidden password input looks like a frozen prompt, and the dense enrollment output gave no sense of progress or separation between scans. The sounds give confirmation without making the user watch the terminal while positioning a finger.

Before / after

Mac password:                              Enter your Mac login password. Nothing
Touch the sensor for view 1 of 4.          appears as you type — that is normal.
Touch the fingerprint sensor now.          Mac password:
Lift your finger from the sensor.
Touch the same finger again now.           Scan 1 of 4
Touch the sensor for view 2 of 4.             touch the sensor
...                                           lift your finger
                                              touch again

Notes for reviewers

  • Both modes share enroll() and exchange_serial(), so the scan formatting and sounds apply to HID and PIV alike. The sounds also fire on other touch-driven commands such as AUTH — intentional, for consistency.
  • sudo -p only affects the first prompt; on a wrong password sudo re-prompts with its own text.
  • Verified: the file parses, python -m unittest discover -s tests passes, and the flow was exercised on real hardware in both HID and PIV mode. Sound choices are easy to swap if Tink/Pop aren't the right feel.
  • Running from source needs Python 3.10+ (tinytouch_keychain.py uses X | None annotations without from __future__ import annotations); macOS system Python 3.9 fails on import. Pre-existing, not touched here.

🤖 Generated with Claude Code

Setup was hard to follow for users new to the terminal. Hidden password
input looked like a frozen prompt, and enrollment printed four full
sentences per scan with no visual separation between scans.

- Tell users that nothing appears as they type, at every password prompt
  (HID Keychain capture, HID re-entry, and the PIV sudo authorization).
- Standardize the PIV sudo prompt to "Mac password: " via sudo -p, with a
  short note that this password is not saved, in contrast to HID where it
  is stored in the Keychain.
- Replace the per-scan sentences with a "Scan N of 4" header and indented
  touch/lift/touch-again steps, separated by blank lines.
- Add macOS system-sound feedback during enrollment: Tink on each touch
  prompt, Pop on lift, and Glass once all four scans complete. Sounds are
  non-blocking and no-op off macOS, when the sound file is missing, or
  when TINYTOUCH_NO_SOUND is set.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant