This document describes FeedZero's security architecture, threat model, and cryptographic design. It is intended for security auditors, self-hosters, and high-risk users who need to understand exactly what protections exist and where the boundaries are.

All claims are verifiable from source code. A source reference table is provided at the end.

FeedZero is used by journalists, activists, and people living under surveillance. FeedZero protects people. Act accordingly. If you find something, please tell us privately — public disclosure of an unpatched flaw can cost real users their safety.

Two private reporting channels:

1. GitHub Security Advisories (preferred): https://github.com/forcingfx/feedzero/security/advisories/new
2. Email: security@feedzero.app (PGP key: TBD — until then, treat the channel as transit-encrypted only and avoid pasting sensitive PoC payloads)

Please do not open a public GitHub issue or discuss the issue on social media until a fix has shipped.

Include:

• A description of the vulnerability and its impact
• Steps to reproduce (or a minimal PoC)
• Affected versions if known
• Any suggested mitigation

We aim to acknowledge within 48 hours and to ship a fix within the disclosure timeline below.

• Standard: 90 days from initial report to public disclosure.
• May extend when user impact requires (e.g. coordinated disclosure with downstream packages, complex remediation, or active exploitation in the wild).
• We will credit reporters publicly when the fix ships, with your consent.

The following are in scope for security reports:

The following are out of scope:

• Social engineering attacks
• Physical access attacks (if someone has your device, derived keys in localStorage can decrypt local data — but cannot recover the passphrase or access the cloud vault)
• Volumetric DDoS (mitigated at the edge by Cloudflare; please report to Cloudflare directly)
• Missing security headers below high severity, where no exploit path is demonstrated
• Issues in dependencies without a demonstrated exploit path in FeedZero

FeedZero is used by journalists, activists, and people living under surveillance. Every design decision assumes a user's safety depends on it.

• Encrypt everything at rest. All feed and article data is AES-GCM-256 encrypted in IndexedDB. Index fields are HMAC-SHA256 hashed.
• Zero knowledge sync. The server stores only opaque encrypted blobs. It never sees plaintext, passphrases, or encryption keys.
• No telemetry. No analytics, crash reporting, tracking pixels, or third-party network calls. The only outbound requests are user-initiated feed fetches and optional sync.
• Minimize trust. The browser is the trust boundary. The proxy and sync server are untrusted intermediaries.

All data in IndexedDB is encrypted before storage and decrypted after retrieval.

AES-GCM provides both confidentiality and integrity via its authentication tag. A random IV per record prevents ciphertext correlation across records.

Queryable fields (feed URL, article feedId, article guid) are HMAC-SHA256 hashed before storage, using a dedicated HMAC key derived from the passphrase with a domain-separated salt (feedzero:index-hmac:v1). Dexie indexes operate on these hashes, enabling lookups without exposing plaintext in IndexedDB.

1. Onboarding: User passphrase is fed to PBKDF2, producing a DB encryption key and an HMAC key (plus vault keys for sync users). Keys are exported as JWK and stored in localStorage under feedzero:derived-keys.
2. Passphrase discarded: The raw passphrase is never persisted. After key derivation, it is discarded from memory.
3. Subsequent sessions: openWithKeys() imports JWKs directly. No passphrase re-entry needed on the same device.
4. Local-only users: A random per-user passphrase is generated at onboarding time. The derived keys are stored; the passphrase is discarded.

Key-data coupling invariant: Stored derived keys must always be able to decrypt local IndexedDB data. Only two operations may modify this coupling: open(passphrase) (derives fresh keys and re-opens the DB) and importAll() (clears and re-encrypts all data).

                    User Passphrase (4 words, ~51.7 bits entropy)
                                    |
                    +---------------+---------------+
                    |                               |
                    v                               v
            +----------------+              +----------------+
            | PBKDF2         |              | PBKDF2         |
            | salt: "feedzero|              | salt: "feedzero|
            | :vault-id:v1"  |              | :enc-salt:v1"  |
            | iter: 600,000  |              | iter: 600,000  |
            | hash: SHA-256  |              | hash: SHA-256  |
            +-------+--------+              +-------+--------+
                    |                               |
                    v                               v
            +----------------+              +----------------+
            | Vault ID       |              | Encryption Salt|
            | (32 bytes,     |              | (16 bytes)     |
            | hex-encoded    |              |                |
            | = 64 chars)    |              +-------+--------+
            +----------------+                      |
                                                    v
                                            +----------------+
                                            | PBKDF2         |
                                            | salt: enc salt |
                                            | iter: 600,000  |
                                            +-------+--------+
                                                    |
                                                    v
                                            +----------------+
                                            | AES-GCM-256    |
                                            | Vault Key      |
                                            +----------------+

• Vault ID and encryption key are cryptographically independent (different PBKDF2 salts). The server-side lookup key reveals nothing about the encryption key.
• Same passphrase always produces the same vault ID and encryption key. No external state needed to recover on a new device.
• The server never receives the passphrase or encryption key. It only sees the vault ID and an opaque encrypted blob.

To prevent traffic analysis from inferring subscription count based on vault transfer size:

1. Vault serialized to JSON
2. Padded to next power-of-2 bucket size (minimum 64 KB, maximum 5 MB)
3. Padding is random hex in a _pad JSON field, generated via crypto.getRandomValues()
4. Random jitter (0-30 seconds) added after the 5-second sync debounce

All proxy endpoints validate target URLs before fetching. The validation function (validateProxyUrl) enforces:

Blocked hostnames (exact match):

• localhost, 127.0.0.1, ::1, 0.0.0.0, 169.254.169.254

Blocked IP ranges:

• 10.0.0.0/8 (RFC 1918)
• 172.16.0.0/12 (RFC 1918)
• 192.168.0.0/16 (RFC 1918)

IPv6-mapped IPv4 detection:

• Blocks ::ffff:x.x.x.x (dotted-decimal form)
• Blocks ::ffff:XXXX:XXXX (hex form) — parses and checks underlying IPv4

Protocol whitelist: Only http: and https: allowed. All other protocols (file://, ftp://, gopher://, etc.) rejected.

Validation timing: Runs before any fetch. Invalid URLs return 400; blocked addresses return 403.

All feed content and extracted page content passes through DOMPurify before rendering.

Allowed tags (40): p, br, hr, h1–h6, ul, ol, li, dl, dt, dd, strong, em, b, i, u, s, del, ins, mark, a, img, figure, figcaption, blockquote, pre, code, table, thead, tbody, tr, th, td, span, div, article, section, sup, sub, abbr, time

Allowed attributes: href, src, alt, title, datetime, colspan, rowspan, class

URI protocol restriction: Explicit allowlist regex permits http:, https:, mailto:, tel:, relative URLs. Blocks javascript:, vbscript:, and other dangerous schemes.

Link hardening: All <a> tags forced to target="_blank" with rel="noopener noreferrer" via afterSanitizeAttributes hook (prevents tab-nabbing).

Data attributes: Blocked (ALLOW_DATA_ATTR: false).

Applied to all non-API responses in both Vercel and Hono deployments:

API (sync) responses include X-Content-Type-Options: nosniff and Content-Type: application/json.

CSP note: style-src 'unsafe-inline' is required for Tailwind CSS v4's inline style generation. No user-controlled CSS is injected.

The standalone Hono server applies a sliding-window rate limiter to all /api/* routes:

Vercel deployments should configure rate limiting at the edge (Vercel Firewall or a reverse proxy).

The sync endpoint returns Access-Control-Allow-Origin: * intentionally — vaults are encrypted and vault IDs are unguessable (64-char hex from PBKDF2, 2^128 possible values).

Complete list of all network requests FeedZero makes:

No other network requests are made. There is no analytics, no telemetry, no crash reporting, no third-party tracking, no CDN fonts, no external scripts.

Raw passphrase is never stored. Derived JWK keys can decrypt local data but cannot recover the passphrase or access the cloud vault from another device.

No dependency makes external network requests. All processing is local except explicit user-initiated proxy and sync operations.

• Self-host the proxy to eliminate third-party URL logging
• Use a longer passphrase (6+ words) if you enable sync — 51.7 bits may be insufficient against well-resourced adversaries with offline access to your vault
• Use encrypted DNS (DoH/DoT) to hide feed domain lookups from your ISP/network
• Use "Delete all data" when leaving shared computers (removes IndexedDB, localStorage keys, and cloud vault)
• Disable cloud sync if you don't need cross-device access — this eliminates the vault as an attack surface entirely
• Use a privacy-focused browser to reduce extension-based attack surface