vdm/docs/05-extension-spec.md

# 05 — Firefox extension specification

Owner: lane **EXT**. TypeScript, MV3, `browser.*` promise APIs, built with esbuild,
packaged with `web-ext`.

## 1. Why Firefox MV3 is actually good news here

Chrome's MV3 removed blocking `webRequest`, which is why IDM-style "grab the download
before the browser starts it" is hard there. **Firefox kept blocking `webRequest` in
MV3.** That means we can inspect response headers and cancel the browser's own download,
which is exactly the interception model IDM uses. Build for Firefox first and do not
compromise the design to stay Chrome-portable.

## 2. Capture pipeline

```
onBeforeSendHeaders ──► stash request headers by requestId (ring buffer, 5 min TTL)
        │
onHeadersReceived ───► shouldCapture(details, headers, settings)?
        │                       │
        │                    yes│
        │                       ▼
        │              cookies.getAll(url) ──► transport.send("capture.offer", {...})
        │                       │
        │              daemon replies {action:"take", taskId}
        │                       ▼
        └──────────────► return {cancel: true}   ← browser never starts the download
```

`shouldCapture` returns true when **any** of:
- `Content-Disposition: attachment` present, or
- the file extension is in the user's monitored list (Options → File Types, mirrored from
  the daemon so the two never disagree), or
- `Content-Type` is in the monitored MIME list and not `text/html`, or
- `Content-Length` > `minSizeBytes` (default 1 MiB) **and** the type is not renderable.

And **none** of:
- the tab is a `blob:`/`data:` URL we generated,
- the host is on the user's exclusion list,
- the response is a navigation to an HTML page,
- the user held the bypass modifier (default: Alt) on the click.

**Fail-open, always.** If the daemon is unreachable or the RPC times out (750 ms budget),
`return {}` and let Firefox download it normally. A download manager that eats downloads
when its daemon is down is worse than no download manager. This rule is non-negotiable and
has a dedicated conformance test.

Belt-and-braces second path: `browser.downloads.onCreated` → if it slipped past the
header hook, `downloads.cancel(id)` + `downloads.erase(id)` and offer to the daemon. Some
downloads (form POSTs, service-worker-generated blobs) only surface here.

## 3. Other surfaces

| Surface | Behaviour |
|---|---|
| Context menu (link) | "Download with Velox" |
| Context menu (image/video/audio) | "Download with Velox" |
| Context menu (page/selection) | "Download all links with Velox…" → opens the batch dialog with the harvested list |
| Toolbar popup | Active downloads with live progress (via `event.task.progress` relayed over the transport), pause/resume, "Add URL", speed indicator, daemon status dot |
| Media panel | Floating in-page button on a tab where a video/HLS/DASH stream was detected — "Download this video ▾" listing quality variants |
| Options page | Transport & pairing · monitored types · min size · exclusion list · default category/folder · bypass modifier · enable/disable capture |
| Keyboard | Configurable command to grab the current tab's URL |

**Media detection:** `webRequest` sniffing for `.m3u8`, `.mpd`, `Content-Type:
application/vnd.apple.mpegurl` / `dash+xml`, plus a content script observing
`MediaSource.addSourceBuffer` and `<video>` `src` changes. The extension sends the manifest
URL + headers to the daemon; the **daemon** parses the manifest and enumerates variants
(`media.listVariants`). The extension never parses HLS — keep the logic in one language.

> DRM-protected streams (Widevine/EME) are explicitly out of scope. Detect them and grey
> out the button with "Protected content" rather than failing mysteriously.

## 4. Transports — the reason this design has two

**Evidence from this machine:** Firefox here is the **Mozilla snap** (`snap list firefox`
→ `154.0`, `mozilla**`). Snap-confined Firefox has a long history of trouble executing
native-messaging host binaries that live outside the snap's world. Meanwhile
`snap connections firefox` shows `network` and `network-bind` **connected**.

So the extension implements a `Transport` interface with two implementations and picks at
runtime:

```ts
interface Transport {
  connect(): Promise<void>
  call<M extends Method>(m: M, p: Params<M>): Promise<Result<M>>
  on(event: string, cb: (p: unknown) => void): void
  readonly state: "connected" | "connecting" | "disconnected"
}
```

### A. `NativeTransport` (preferred when it works)
`browser.runtime.connectNative("com.velox.host")` → `velox-nmhost` → Unix socket.
Manifest installed to **all** of these, because the right one depends on how Firefox was
installed:
- `~/.mozilla/native-messaging-hosts/com.velox.host.json` (deb/tarball **and snap** —
  spike S1 proved snap Firefox reads the real home here, not `$SNAP_USER_COMMON`; see
  `docs/adr/0003-native-messaging-under-snap.md`)
- `/usr/lib/mozilla/native-messaging-hosts/com.velox.host.json` (system-wide; deb/tarball
  only — snap Firefox does not read it, per S1)
- `~/.var/app/org.mozilla.firefox/.mozilla/native-messaging-hosts/` (flatpak)

The host binary runs **outside** the snap sandbox with the real `$HOME` and real
`$XDG_RUNTIME_DIR`, so it reaches `veloxd`'s Unix socket directly (ADR 0003 §Q2).

### B. `WebSocketTransport` (fallback, guaranteed to work under snap confinement)
`ws://127.0.0.1:<port>` where the port is discovered by trying a small fixed range and
verifying a `session.hello` handshake — the extension cannot read
`$XDG_RUNTIME_DIR/velox/ws.port`, so the daemon binds the first free port in
`52000–52016` and the extension probes them.

**Pairing (first run only):** the extension connects and calls `session.pair`. The daemon
pops a GUI/desktop-notification dialog: *"Firefox is requesting to connect to Velox.
Pairing code: **4821**. [Allow] [Deny]"*. The user clicks Allow (or types the code in the
extension options if the GUI isn't running). The daemon returns a 256-bit token; the
extension stores it in `browser.storage.local` and sends it on every subsequent connect.

**Security requirements (non-negotiable, conformance-tested):**
- Bind `127.0.0.1` only — never `0.0.0.0`.
- Verify `Origin: moz-extension://…` on the WS upgrade, and require the token.
- Rate-limit failed auth (5/min, then a 60 s lockout) so the token can't be brute-forced
  by another local process.
- Token is per-install, revocable from Options → "Unpair", and stored in the daemon's DB
  as a hash, not plaintext.
- **Never** expose a method that can write to an arbitrary path without a task the user
  approved. The extension can request a download; it cannot ask the daemon to write to
  `~/.bashrc`.

## 5. Startup UX when the daemon is missing

Popup shows a red dot and: *"Velox isn't running. [Start it] [Install]"*. `[Start it]`
tries `session.hello` again after asking the native host to spawn the daemon; if the
native transport is unavailable, link to install instructions. Capture stays fail-open
throughout — Firefox keeps downloading normally.

## 6. Build & test

```
extension/
├── manifest.json                 # MV3, permissions listed and justified in a comment
├── src/background/index.ts       # event page entry
│   ├── capture/{headers,rules,downloads-api,media}.ts
│   ├── transport/{index,native,websocket,discovery}.ts
│   ├── context-menus.ts  badge.ts  state.ts
├── src/content/{media-observer,link-harvest,video-panel}.ts
├── src/popup/  src/options/      # plain TS + minimal CSS; no framework needed
└── src/shared/protocol/          # GENERATED from contracts/ — never hand-edit
```

- Unit: **vitest** with `webextension-polyfill` mocked; every `shouldCapture` decision gets
  a table-driven test (this is where the bugs will be).
- Integration: against `tools/mockd` over WebSocket.
- E2E: **Playwright** with a real Firefox and a real `veloxd`, asserting a real file lands
  on disk with the right bytes. Lives in `tests/e2e/`.
- Lint: ESLint + `web-ext lint` (AMO rules) in CI from day one — finding out at submission
  time that a permission is disallowed costs a week.

## 7. Permissions (keep this list short; AMO reviews it)

`webRequest`, `webRequestBlocking`, `downloads`, `cookies`, `contextMenus`, `storage`,
`notifications`, `nativeMessaging`, `<all_urls>`.

`<all_urls>` is unavoidable for a download manager but is the main review-friction item:
document *why* in the AMO submission notes and in the source, and make the exclusion list
prominent in Options. The submission-ready copy of this table lives in
`extension/docs/amo-permissions.md`, committed alongside the manifest it explains.

## 8. Popup and Options talk to the background page over a relay, not directly

`popup/` and `options/` are separate documents (a browser action popup and an
`options_ui` page) — they cannot import `background/index.ts`'s live `VeloxTransport`.
`background/bridge.ts` relays it over one `browser.runtime.connect` port per document:
`call`/`subscribe`/`getStatus`/`reconnect`/`pair`/`unpair`/`setOverride` requests in,
`result`/`event`/`status`/`pairError` responses out. `shared/panel-client.ts` is the
client side both surfaces use. The status payload carries `kind` (which transport
implementation is live) alongside the existing `TransportStatus`, because Options needs
it: `settings.set` and `rules.upsert` are privileged, uds-only methods (see
`shared/protocol/methods.ts`'s `METHODS` table), so the capture-policy edit form only
ever unlocks when the active transport is native messaging. Over WebSocket — the
default, guaranteed path per ADR 0003 — Options renders the daemon's policy read-only
via `capture.getRules` rather than pretending it can write settings the protocol
refuses over that transport. The one Options setting that genuinely belongs to the
extension (not the daemon) — the default category applied to extension-initiated
downloads — lives in `browser.storage.local` via `options/prefs.ts`, the same place the
pairing token and transport override already live.

Streaming-media detection (build step 7) also splits down this line: `capture/media.ts`
(background, webRequest-based) recognizes `.m3u8`/`.mpd` URLs and their content types
and tells the tab's content script over `runtime.sendMessage`
(`background/media-bridge.ts`); `content/media-observer.ts` independently watches the
page's own `<video>` elements for the same signal. Either one showing up opens
`content/video-panel.ts`'s "Download this video ▾" panel, which calls
`media.listVariants`/`media.addVariant` through the background page and greys out any
variant (or the whole manifest) flagged `drm`/`drmProtected` with "Protected content" —
the extension never parses the manifest itself.