If you discover a security vulnerability in Headroom, please report it privately rather than opening a public issue.
Contact: Use GitHub's private vulnerability reporting to report security issues confidentially. Only the maintainer can see your report.
Please include:
- A clear description of the vulnerability
- Steps to reproduce
- Affected versions (or commit hash)
- Any suggested mitigations
You should receive a response within 72 hours. After the vulnerability is confirmed and a fix is prepared, we will coordinate disclosure timing.
Headroom is designed with these security properties:
Headroom reads conversation text only to count tokens in memory. The
extension stores only token counts per round — never the text of your
prompts or AI responses. Neither browser.storage.local nor Upstash Redis
ever contains your conversation content.
This is a structural guarantee, not a policy: the DialogueRecord / RoundRecord
data types have no fields for text — only numeric counters and platform-stable
identifiers (messageId, order, n, promptTokens, answerTokens, total,
createdAt).
Your Upstash REST URL and token are stored in browser.storage.local only.
When settings are synced to Upstash (headroom:settings key), credentials are
stripped — the cloud copy contains only thresholds, language preference, and
context limit overrides. This is enforced by toCloudSettings() in
utils/cloud-settings.ts, verified by the probe script
(scripts/probe-upstash.mjs), and covered by unit tests.
Headroom uses a Bring Your Own Key (BYOK) model. There is no Headroom-operated server. Your token counts live in your personal Upstash Redis instance, under your own account. Headroom never phones home and has no third-party analytics or tracking.
The extension requests only the permissions it needs:
| Permission | Purpose |
|---|---|
storage |
Local settings + conversation cache |
webRequest |
Detect round completion + conversation deletion |
alarms |
Periodic zombie conversation cleanup (60min schedule) |
tabs |
Tab-switch gauge projection + dialogue title query (no reading of non-platform URLs) |
sidePanel |
Browser-native side panel UI |
host_permissions |
Access conversation history on supported AI platforms |
Headroom does NOT request cookies, unlimitedStorage, or any permission that
would allow it to read data beyond the supported AI chat platforms.
Headroom is Manifest V3 only. MV3 enforces a stricter security model than MV2: service workers (not persistent background pages), declarative net request rules, and no remotely-hosted code.
Only the latest released version receives security patches. There are no LTS releases or backport branches at this stage of the project.