Design & Security

Design

Two-part architecture

• Website frontend: the chat interface, model lists, provider configuration, and other user-facing features.
• Browser extension backend: the local backend that stores API keys, chats, files, and settings, and communicates with provider APIs.

Data flow

Website UI                 Browser extension              Provider API
    |                              |                            |
    |-- Save API key ------------->|                            |
    |                              |-- Store key locally        |
    |<-- Saved --------------------|                            |
    |                              |                            |
    |-- Chat request ------------->|                            |
    |                              |-- HTTPS request + key ---->|
    |                              |<-- Streamed response ------|
    |<-- Streamed response --------|                            |
    |                              |-- Save chat locally        |
    |                              |                            |

The website sends requests to the extension through Chrome's extension messaging system, and the extension communicates directly with the selected provider.

Why the split?

The two-component design meets four requirements:

• Easy installation: the backend extension is installed and updated through the Chrome Web Store.
• API key separation: stored keys remain inside extension storage instead of website storage.
• Fast updates: website-owned model lists, provider configuration, and UI features can be released quickly.
• Lightweight hosting: AirmailAI.net is static files served from a CDN.

Security

Website and extension identity

Release builds validate both sides of the website-extension connection before sharing data. The extension accepts external connections only from AirmailAI.net, while the website connects only to the fixed extension ID published through the Chrome Web Store. Local development access is opt-in and excluded from production builds.

API key handling

When you save an API key, the website sends it to the extension for storage in local, non-synchronized extension storage. The extension only uses the key when authenticating a request to the specified provider. The website-extension protocol can save a key, delete it, check whether it exists, or ask the extension to use it, but it has no operation that returns the stored key to the website.

Once a key is saved, your browser keeps it in storage scoped to the AirmailAI extension. Websites cannot access that storage, and theextension only accepts requests from AirmailAI.net. Even AirmailAI.net has no protocol operation for retrieving the raw key. Under your browser's normal security model, visiting a malicious website cannot expose your saved keys.

Untrusted content and injection

User messages, imported chats, and provider responses are treated as untrusted content. Chat imports are parsed into a narrow schema, bounded by file, chat, message, and field-size limits, and only recognized fields are retained.

Messages support Markdown, but raw HTML is displayed as plain text. Before anything is shown, DOMPurify removes potentially unsafe content. Features such as search highlighting also ensure message content is treated as text, not executable code. AirmailAI does not include third-party analytics or remotely hosted application scripts.^*

Local data and extension permissions

AirmailAI relies on Chrome's extension security boundaries to separate AirmailAI extension data and privileges from other websites. The extension requests the storage permission plus host access for the supported provider API domains.

• API keys are stored in non-synchronized chrome.storage.local.
• Chats, attachments, and file metadata are stored in the extension's local IndexedDB database.
• UI, model, and feature settings use chrome.storage.sync and may sync through your browser account when browser sync is enabled.
• Small website-only display preferences are cached in the website's local storage.

The website can request chats and files as needed to display and manage them.

Provider boundaries

Provider requests use HTTPS and travel directly from the extension to the selected provider. Depending on the features used, the provider may receive the API key, prompts, relevant conversation history, files, tool inputs, and settings required to fulfill the request. OpenRouter requests may also be handled by its downstream model and feature providers.

Provider-side files, containers, requests, and responses are governed by that provider's controls and policies. Deleting local AirmailAI data does not necessarily delete copies held by a provider.

Security boundaries

AirmailAI's protections operate within your browser's normal security model. They do not attempt to protect data from someone who controls your device or browser profile, or from another extension you have granted permission to inspect or modify AirmailAI.net. Once data is sent to a provider, that provider's security and privacy controls apply.

Report a security issue

Please report security issues privately by emailing security@blake-dev.net. Do not include API keys, private conversations, or other sensitive data, and do not report vulnerabilities through a public GitHub issue. AirmailAI's source code is available on GitHub.