How It Works

How it works

This page describes what a request goes through, from the page to the store and back. It stays at the boundary this repository can speak to: what the extension does, and what it hands to the Locke desktop app. What happens inside the desktop app is its own product's story.

The request lifecycle

1. A page you're on tries to send data to an AI surface. The extension's page script wraps fetch and XMLHttpRequest, so a bodied request to a catalogued AI host is seen before it leaves.
2. The request is held. The exact bytes are captured; nothing has gone to the network yet.
3. It is relayed to the Locke desktop app over browser native messaging — a local channel to a helper the desktop app installed. Not a network hop; the browser never opens a socket to the app.
4. Locke answers with a verdict:
   • allow — the original request is sent, untouched.
   • redact — Locke returns a rebuilt request with sensitive spans replaced; that is what goes to the AI provider.
   • block — nothing is sent. To the page it looks like a failed network request, and the extension records a plain-language reason.
5. No verdict? No send. If the desktop app is unreachable, or doesn't answer in time, the request is blocked. Failing closed is the point: an error should never become the path by which data leaks.

What's in scope

• Chat and prompt traffic to the catalogued AI web apps
• Attachment uploads those pages make, including direct-to-storage uploads
• The AI-answering search engines in the catalogue

The catalogue ships inside the extension and is visible in this repository (shared/ai-surfaces.json and the generated files beside it).

What's deliberately NOT covered

Honesty about limits beats silence: HONEST.md is the complete, maintained list. Highlights: WebSocket traffic, prompts typed straight into the address bar or a ?q= link, and upload shapes the extension doesn't recognise. If a gap matters to you, that document is the truth source.

Verifying instead of trusting

• Loopback-only: CI fails any change that introduces a non-loopback endpoint into the shipped payload (scripts/audit-payload.mjs).
• Reproducible builds: two builds of the same commit are byte-identical, checked on every push.
• Zero runtime dependencies: package.json declares none — what ships is what you can read here.

The licence permits noncommercial verification, including rebuilding — see FAQ.