cthulhu/docs/tentacle-secret-entries.md

Secret entries in Tentacle forms

Transient interaction forms support secret: true on an entry (kind: 2). The Go SDK exposes it as tentacle.Element.Secret; Python commands return the same JSON property in their form dictionaries. For example:

tentacle.Element{
    ID: "key", Label: "Channel key", Kind: tentacle.Entry,
    Secret: true, Required: true, MaxLength: 512,
}

{"id": "key", "label": "Channel key", "kind": 2,
 "secret": True, "required": True, "max_length": 512}

These entries use the existing host-owned, focus-free editor. They do not create a GTK entry or publish a plaintext accessible text object. Keyboard capture leaves application focus in place, and the reader presents the form directly. Ordinary key echo and review commands remain suppressed during modal capture. Only the masked presentation reaches the speech/Braille output paths, including their debug-output logging. Field labels and titles are ordinary public text; never put credentials in them, command descriptions, or status messages.

On focus, speech announces the label, “password edit”, and character count. Typing and pasting announce inserted character counts; deletion announces the deleted count. Cursor movement says “Hidden character” or “End of text”. Braille shows one asterisk per Unicode code point and a corresponding caret position. Character counts, selection length and caret position are intentionally visible. This is code-point editing, like the existing ordinary entry, not grapheme editing.

Ctrl+A selects all. Ctrl+C and Ctrl+X announce that copy and cut are unavailable, without changing the selection, value or clipboard. Ctrl+V explicitly reads the clipboard and inserts valid single-line text within the existing length limit. Tab and Shift+Tab traverse normally. Enter submits and Escape cancels.

Successful submission delivers the real value in values["key"].text to the registered continuation. Cancellation, capture revocation and failed capture closure deliver no values. The editor drops its references to secret strings when it closes; Go does not guarantee memory erasure. The receiving Tentacle is responsible for using the submitted secret without logging or presenting it. This feature does not sandbox the Tentacle or change the interaction grant.

Secret fields are rejected on non-entry controls and on persistent preference pages, including page-value validation. Generic reader settings storage is not a credential store. Malformed flags (including null, non-booleans, duplicate keys and case variants) fail validation. Omitting secret preserves ordinary entry behavior. Older readers reject the unknown property rather than treating the control as a normal entry. There is no protocol 1.1 negotiation or minimum reader-version gate in this increment; Remote remains unpackageable until those interfaces exist. Never retry a rejected secret form as an ordinary entry.

Verification

Focused automated checks:

GOCACHE=/tmp/cthulhu-go-cache GOPROXY=off go test -race ./internal/interaction ./internal/tentaclewire ./internal/tentacle ./sdk/... -count=1
GOCACHE=/tmp/cthulhu-go-cache GOPROXY=off go test -race ./internal/app -run 'TestInternalUI|TestReaderTentacle' -count=1
python3 tests/native_internal_ui.py

The private Xvfb/D-Bus harness tests actual key capture, masked speech requests, copy/cut denial, paste, submission, unchanged application focus, and restored typing. Unit checks cover masked Braille frames and caret positions, Unicode editing, malformed flags, cancellation/revocation/error cleanup and both SDKs across real child-process IPC. The existing ordinary entry, action menu, emoji picker and clipboard tests remain part of the native harness.

These checks do not establish audible output or physical Braille acceptance. Remote has no connection UI to launch yet. When a consumer is integrated, its live test must check the announced label/count, typing and deletion without plaintext echo, masked Braille and caret, selection/copy/cut/paste, Tab/Shift+Tab, Escape, and typing into the original application after the form closes. Existing Wormhole ordinary entries must retain their text echo and copy/cut behavior.