47 lines
2.4 KiB
Markdown
47 lines
2.4 KiB
Markdown
# Clipboard and QR presentation
|
|
|
|
`crates/storage` owns secret-presentation lifecycle and derived QR data. The
|
|
CLI receives an already selected `PresentationSecret` or generated password and
|
|
only writes storage-produced status or terminal-rendering bytes. It never
|
|
launches `xclip`, `wl-copy`, `pbcopy`, `qrencode`, an image viewer, or a shell.
|
|
The same byte-oriented APIs are ready for pass-otp code and URI results without
|
|
placing OTP parsing or calculation in a frontend.
|
|
|
|
## Clipboard lifecycle
|
|
|
|
The default clipboard lease is 45 seconds, matching upstream `pass`.
|
|
`clipboard_timeout_seconds` may configure 1 through 300 seconds. Before copying,
|
|
storage snapshots an existing UTF-8 clipboard value. At lease completion or
|
|
cancellation it reads the clipboard again:
|
|
|
|
- if the copied secret remains current, storage restores the previous text or
|
|
clears a previous empty/non-text clipboard;
|
|
- if another application or the user supplied newer contents, storage leaves
|
|
those contents untouched;
|
|
- if cleanup cannot be verified or completed, the operation returns a typed
|
|
cleanup failure rather than claiming success.
|
|
|
|
The CLI deliberately remains alive during the lease. This lets X11 and Wayland
|
|
serve the selection and guarantees cleanup without spawning a daemon or helper.
|
|
Linux also marks copied text with the commonly supported password-manager hint
|
|
to discourage clipboard-history retention. macOS uses NSPasteboard, Windows
|
|
uses the native clipboard, and Linux uses direct X11 or Wayland data-control
|
|
protocols through the safe `arboard` adapter. Unsupported targets return a
|
|
typed unavailable result. Tests inject a byte-oriented backend and cover
|
|
expiry, restore, clear, cancellation, failure, and newer-content races without
|
|
touching the developer clipboard.
|
|
|
|
## QR data
|
|
|
|
`QrMatrix` encodes secret bytes with the pure-Rust `qrcode` implementation and
|
|
returns only dimensions and dark/light module queries. Its module buffer,
|
|
terminal rendering, and source payload all use zeroizing/redacted storage
|
|
objects. The terminal renderer supplies the standard four-module quiet zone,
|
|
square half-block cells, and no plaintext label or payload. Frontends can draw
|
|
the same matrix natively without regenerating or interpreting it.
|
|
|
|
Round-trip tests decode generated password, Unicode, and `otpauth://` matrices
|
|
with the test-only `rqrr` decoder. Empty and oversized payloads are typed errors,
|
|
and CLI tests prove `show` and `generate` clipboard/QR modes never emit their
|
|
plaintext values.
|