Privacy and credentials#

Omagma connects directly to Google’s APIs. Every configured account authorizes separately, and mail, unread counts and browser profiles remain account-specific. Public examples and screenshots use fictional accounts.

Bar access#

The bar requests gmail.readonly. Google classifies this as a restricted scope that permits broader mailbox reading than the bar actually uses. Google’s scope definitions.

The bar fetches an Inbox page of at most 30 messages per account, with selected metadata and snippets. It does not download full bodies or attachments, change labels or read status, or send mail. Its cache lives in bounded process memory and disappears when the backend exits. The bar does not save mail history or mail logs to disk.

Gmail links open in the account’s configured Chrome profile. Reading a message in Gmail is then handled by Gmail itself.

Refresh tokens use the configured credential store. The default credentialStore: "keyring" uses Secret Service on Linux or the current default user Keychain on macOS, with Omagma’s service namespace and verified account identity. The explicitly chosen "file" store uses credentialDirectory, an absolute canonical private directory with mode 0700 and owner-only 0600 token files. File-store refresh tokens are unencrypted on disk. Anyone able to read them can use the corresponding grants; keep them outside Git, shared folders and public artifacts. Access tokens remain in backend memory. Token contents never go in command-line arguments or the bar UI/terminal response frames.

With the Mac keyring store, entries trust Omagma and Apple’s signed /usr/bin/security helper, allowing reads and scoped deletion fallback after a re-signed binary upgrade. Native checks target the exact default keychain and account/grant, suppress their own UI, and refuse a known locked keychain before starting a signed helper. If the lock state changes during handoff or an item’s ACL was edited, the operating system may still request permission. A blocked helper is canceled at Omagma’s finite deadline. Unlock the keychain explicitly and retry if Omagma reports KeyringUnavailable. This is per-user credential storage, consistent with Linux Secret Service, rather than isolation from programs with equivalent user access.

Mac Agent-enabled setup uses the same binary with file credentials to avoid Keychain audit-session restrictions. It does not grant an agent sandbox access to config, grants, cache, credentials or Google network endpoints; those permissions remain necessary. A working local TUI does not establish that an agent subprocess can read the account.

omagma credentials status --json reports credential-store status without token contents. omagma credentials migrate --to file --directory ABS or --to keyring reuses existing config and grants without Google reauthorization. Run migration where the source is accessible. Destination copies are verified before the config switches atomically, and source copies are retained. Later migrations respect the current store and grant registry, so retained copies do not restore locally revoked credentials. Restart open sessions after switching. Migration back to Keychain does not encrypt or remove retained file copies; account for them when removing local credentials.

Consent opens your configured Chrome profile and returns through a temporary local IPv4 callback listener. Omagma verifies the random state, PKCE exchange and returned Gmail identity before accepting the grant. The consent command has a 180-second deadline. Keep the downloaded Google OAuth registration JSON and account configuration private, outside Git. Google treats installed applications as unable to keep registration secrets confidential; refresh tokens still need protection. Google’s installed-app model.

Terminal client#

The experimental TUI and CLI can read complete messages, threads and attachments using an existing read-only grant. Sending, mailbox changes and contacts require separate terminal authorization. Terminal refresh tokens use a separate namespace in the selected credential store. If you use a bar/read-only registration, broader terminal access uses a different Google OAuth registration so the read-only authorization remains intact. Terminal-only setup needs just one registration. Installation or read access alone does not authorize an agent to send mail or change contacts.

By default, terminal modes save cached mail, local drafts, contacts, Calendar data and operation receipts in owner-only directories and files. The defaults are $XDG_CACHE_HOME/omagma/terminal or $HOME/.cache/omagma/terminal; directories use mode 0700 and files use 0600. Live and fixture data have separate namespaces, and account/message filename components are hashes. The default store keeps mail and drafts as plaintext on disk. Filesystem permissions restrict access; a backup or administrator with file access can still read them.

Omagma 0.2.9 adds an optional encrypted native vault with explicit migration and a password-unlocked daemon for the TUI, CLI and SSH clients. Migration preserves the original plaintext source; explicit attachment saves, exports and external editor files also remain plaintext outputs. The vault guide explains activation, recovery and these storage boundaries.

The cache keeps the newest mail within message-count and byte quotas. Old-tail eviction removes mail and its cached bodies while preserving drafts and uncertain-operation receipts. Clearing the mail cache also preserves drafts, contacts and receipts. See cache behavior. Omagma also saves account addresses, mailbox/selected-message context and key/layout preferences in the private omagma/ui.json configuration file.

The CLI returns requested mail and contacts to its caller. Treat its stdout, redirected files and agent logs as private. Local send and invitation receipts contain account/message identities and submission state; they are private too. An uncertain send is retained for review rather than automatically resubmitted.

Browser WebAssembly client#

The optional browser build keeps OAuth credentials in tab memory. Connect uses existing terminal grants through the guarded loopback server or a private connection file. Google requests go directly from the browser to Google; the page does not broaden the grant. Browser JavaScript can access credentials loaded into that page, so use the controlled local page or a trusted deployment.

Mail/contacts and drafts/send receipts use separate bounded IndexedDB stores. Saved browser mail and drafts are plaintext browser data, not encrypted at rest. Browser same-origin storage controls apply; native owner-only file modes do not govern IndexedDB. Tokens are excluded from both stores. Saved drafts remain after reload/disconnect and require fresh account verification with the same registration/grant before Omagma displays them. Browser storage is local to the browser profile and page origin; another server port has separate storage.

Clear cache removes mail/contact snapshots and preserves drafts/receipts. Reviewed draft discard removes that verified account's selected local draft. Saved drafts… offers reviewed cleanup of eligible saved rows and settled history; unconfirmed sends, unconsumed receipts and unreadable rows are kept. Unconfirmed sends protect their recovery draft without automatic replay; check the named account's Sent before acknowledging. Disconnect clears credentials from the page without revoking Google authorization or deleting saved drafts. See browser workflows and limits.

Message rendering and attachments#

Display text is sanitized to remove terminal controls and directional formatting. A supplied plain-text body takes precedence. HTML-only mail becomes bounded formatted text; scripts, stylesheets, remote images and other remote resources never run or load.

Markdown composition retains editable source in the private draft and derives outgoing HTML plus a plain-text alternative locally. Raw HTML is escaped; remote Markdown images remain inert text or safe links. Fenced-code highlighting never executes code or loads a grammar from the network. The small “Sent with omagma” footer uses the approved logo embedded in the email, the volcano emoji and a public project link; it contains no remotely fetched image or tracking request. Previewing, changing format and autosaving do not send mail.

The reader’s link chooser opens only an explicitly selected HTTP(S) URL in the account’s Chrome profile. Received attachments are saved only after you choose a destination; existing files are not overwritten. Its Open action delegates a saved, private file of a supported document/image type to the desktop viewer. Reading mail does not automatically launch a link or attachment.

Fixture providers make no Gmail API or credential-store requests. You can try fictional mail with omagma tui --fixtures; this is optional and does not grant live permissions.

Release checks#

The TUI's daily release check contacts the official public GitHub release API. A detected Homebrew install also checks the public tap formula. These requests contain no Google credentials or account/mail data and require no account grant. Automatic checking can be turned off in Updates or with omagma updates automatic off. A bounded private status file stores release versions, check times, retry delays, dismissal and this preference; see updates.

Disconnect or remove#

Removing the Linux widget, uninstalling Homebrew’s omagma formula, or removing a manually installed executable leaves your private configuration, cache and credentials available for later use. The bar protocol’s disconnect command removes its local account token from the selected store and clears its memory cache. omagma terminal-auth revoke --account ACCOUNT removes the terminal token from the selected store and its registry entry; use your usual --config and --grant-file options when you selected non-default paths. Local removal from the active store does not remove source copies retained by an earlier migration.

These local removals do not revoke Google’s grant or erase terminal cache files. To invalidate Google-side access, revoke Omagma in your Google Account. To delete local mail, review the private cache directory and any files you explicitly saved. Keep real mail, addresses, message IDs, OAuth downloads and callback URLs out of public issues, screenshots and shared logs.