Skip to content
WM KeyboardWM Keyboard
Accessibility

Clipboard system

How WM Keyboard captures, stores and writes clips on top of Android's clipboard, and the security boundary around the history.

Scope. The clipboard history the keyboard keeps beside Android’s own clipboard: capture, storage, the keyboard’s writes to the system clipboard, backup and sync. Not covered: the user guide, which is Clipboard manager.

The hardening described here came from a proposal and prototype by saen1a in wasi-master/wmkeyboard#1215. Parts of the prototype were taken in, adapted to the current code; the decisions page lists what was and what wasn’t, and why.

  • A history. ClipboardStore (core/content) keeps text, rich text, links, pictures, files, folders and videos, persisted as one JSON snapshot at files/clipboard/history.json. Pictures are copied into files/clipboard/images/; files, folders and videos are kept by content URI and stay the copying app’s.
  • A listener. WMKeyboardService registers an OnPrimaryClipChangedListener and files each copy, through the user’s gates (history on, not incognito-paused, not a password field unless the setting says so) and the user’s sensitive-clip handling.
  • One write path. Everything the keyboard puts on the system clipboard goes through ClipboardWriteGate (feature/ime).
  • One import boundary. Every clipboard bundle that arrives from outside, in a settings backup or a sync, goes through ClipboardSyncSanitizer (core/content) before it is written.

These hold in the code today. Each one names what enforces it.

InvariantEnforced by
The user’s sensitive-clip handling decides what happens to a secret. “Keep it like any other clip” (the default) keeps it exactly like any other clip.SensitiveClipHandling, read in the listener and in recordPrivateCopy
Under “Hide it and delete it quickly”, an unpinned secret is never written to history.json.ClipboardStore.memoryOnlySensitive, applied in save()
No existing clip is cut or dropped by an update: caps apply to new copies only.ClipboardStore.addTextual, editText; restore never caps
Every keyboard write that needs Android’s sensitive flag gets it.ClipboardWriteGate.writeText/writeClip with sensitive = true
A write the listener must not file again is recognised by a token, not by its text.SelfWriteLedger, ClipboardWriteGate.consumeSelfWrite
A crafted or damaged bundle cannot delete a file, inject a non-text clip, duplicate an id, or make the whole history unreadable.ClipboardSyncSanitizer.sanitize, deconflictIds
Android Auto Backup and device transfer never see the clipboard folder.data_extraction_rules.xml, backup_rules.xml, ClipboardBackupRulesTest
Diagnostics never carry clip content.ClipboardDiagnostics, counters only
FileModuleRole
ClipboardStore.ktcore/contentThe history, its caps and the memory-only rule
ClipboardSyncSanitizer.ktcore/contentThe raw-JSON boundary for backup and sync bundles
ClipSensitivity.ktcore/contentThe “looks like a password or a code” heuristic
ClipboardWriteGate.ktfeature/imeEvery keyboard write to the system clipboard
SelfWriteLedger.ktfeature/imeOne-shot tokens for writes the listener skips
ClipboardDiagnostics.ktfeature/imeContent-free capture counters
KeyboardClipboard.ktfeature/imeThe private in-memory copy (incognito, private copies)
WMKeyboardService.ktfeature/imeThe listener, recordPrivateCopy, configureClipboardStore
SettingsRepository.ktcore/settingsportableClipboard, applySyncedClipboard, the backup restore