# Encrypted text chat through Gmail

Desktop 0.18.0 (Linux and Windows) and Android 2.12.0 replace the active Matrix text-chat flow with Gmail API delivery. Personal Gmail accounts are supported through the existing Google connection and `gmail.modify` permission. Workdesk no longer needs Workspace Chat permissions, a Matrix login, a public-key directory server, or an existing Google Chat conversation for text chat.

## Start a conversation

1. Both people install this version and use **Connect Google** with their own Gmail account. Existing Gmail permission is sufficient.
2. Open **SecureComm** on desktop or **Chat** on Android. The page is titled **Encrypted Gmail chat**. Choose **Enable Gmail chat** to check access.
3. Under **Identity keys**, unlock the existing SecureComm key. On another device, restore/merge the original encrypted offline key backup, then unlock it. Generate a key only for an identity that has never had one. Drive keys are separate.
4. Exchange only the public keys. In **Contacts & verification**, enter the person's Gmail address and public key. Existing local contacts can be imported for review.
5. Compare the complete key fingerprint with the person through a trusted separate channel, then confirm it. A changed key requires verification again. Blocking a contact prevents send/fetch operations.
6. Select the contact under **Conversations** and send text. Workdesk encrypts and signs locally before sending the email. Both people must use Workdesk to read these messages. Ordinary Gmail shows ciphertext.

The selected conversation refreshes every 15 seconds while the chat screen is active and keys are unlocked. **Refresh messages** checks immediately; **Load earlier messages** follows Gmail pagination. Search filters the messages already cached on the device. There is no new Gmail push/background notification service in this release. Gmail delivery delays, spam filtering and API limits still apply; check Spam in Gmail if expected encrypted mail does not arrive.

## Encryption and delivery

OpenPGP.js on Electron and PGPainless on Android use standard signed OpenPGP encryption to the recipient and the sender's own key. Private keys and passphrases stay local. Retained private and verified public keys allow older messages to be decrypted after rotation/backup merge. This uses long-lived OpenPGP identity keys, not a forward-secret ratchet.

The encrypted JSON envelope contains version, UUID, sender, recipient, text and time. Only correctly signed, encrypted envelopes matching the selected participants are displayed. Email headers, Google routing and subject matches do not establish a sender's identity. Messages with forged participants, wrong signatures, invalid fields or plaintext are ignored. A previously accepted message UUID cannot be overwritten with different text or participants.

Gmail receives ciphertext, both email addresses, delivery times and a fixed subject, **Workdesk encrypted chat v1**. The body contains only a version marker and armored encrypted data. No message text is included in the subject, headers or notifications. The message is also present in Sent mail. Incoming ciphertext is left in the Gmail mailbox; Workdesk does not install filters, delete mail or hide mail automatically.

A local pending record is saved before delivery. A lost response is shown as **Delivery uncertain**. Refresh searches for that same signed UUID before the user decides whether to send again; no automatic POST retry or plaintext fallback occurs. **Sent** means Gmail accepted the send, not that the recipient read it. Repeated mail copies are deduplicated. Local history is encrypted with the existing OS credential vault or Android Keystore. Cache limits fail explicitly instead of dropping existing history.

## Previous history and server retirement

Desktop **Local history** shows the decrypted Matrix text already cached locally. Android retains the original encrypted Matrix database, session and keys, and offers **Read cached history offline** using a disposable copy with SDK HTTP routed to a rejecting loopback proxy. Only what the retained local SDK cache can expose is shown. Original stores are never logged out, cleared, or overwritten. Uncached server history and uncached attachment bytes cannot be fetched by this screen.

Normal builds no longer start or restore a Matrix transport or its sync, call or FCM services. The Matrix SDK remains bundled solely for local archive reading and legacy fixture tests. Calls and attachments are outside this text-chat migration. Previous published clients still need their server; this source change does not stop or delete the live server. Publish and update all clients, preserve any required old history, then retire the server separately. Do not clear app data or uninstall without preserving keys and local history.

## Verification

- `npm test`: simulated Gmail delivery, real encryption, verification gates, duplicate handling, uncertain-send reconciliation, local archive preservation, changed-key invalidation, and forged/unsigned envelope rejection.
- `npm run test:gmail-chat-ui`: fingerprint confirmation, key unlock, compose/send and read-only local archive with fixtures.
- `node scripts/gmail-chat-interop-test.mjs prepare`, Android JVM unit test with `-PworkdeskGmailFixtureDir="$PWD/.test-build/gmail-chat-interop"`, then `node scripts/gmail-chat-interop-test.mjs verify`: actual Electron → Android → Electron MIME and encrypted Unicode text interoperability, no external email delivery.
- Normal Android emulator style suite includes Chat navigation and enlarged text.

Gmail API references: [sending MIME messages](https://developers.google.com/workspace/gmail/api/guides/sending), [listing/searching messages](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.messages/list).