merge: lane/ext

extension/src/background/capture/downloads-api.ts

@@ -0,0 +1,186 @@
+// The downloads.onCreated safety net.
+//
+// Some downloads never reach the blocking header hook — a form POST's result, a
+// service-worker-generated response, a click that Firefox routed straight to its own
+// downloader. Those surface here. If one looks like something the daemon should own,
+// offer it FIRST and only then cancel + erase Firefox's copy — so a failed or slow offer
+// can never leave the user with no download at all.
+//
+// blob:/data: downloads are left to Firefox: their bytes exist only in the page, and the
+// daemon cannot fetch a blob URL.
+
+import type { CaptureOfferParams, CaptureOfferResult, CaptureRules, Cookie } from '../../shared/protocol/index.js';
+
+import { guessFilename, toWireCookies, type CookieRecord } from './index.js';
+import { filenameExtension, hostExcluded } from './rules.js';
+
+export interface DownloadItem {
+  id: number;
+  url: string;
+  finalUrl?: string;
+  referrer?: string;
+  filename?: string;
+  mime?: string;
+  /** -1 when unknown. */
+  fileSize?: number;
+  /** -1 when unknown. */
+  totalBytes?: number;
+  state?: 'in_progress' | 'interrupted' | 'complete';
+}
+
+interface DownloadEvent<L extends (...a: never[]) => void> {
+  addListener(listener: L): void;
+  removeListener(listener: L): void;
+}
+
+export interface DownloadsApiLike {
+  onCreated: DownloadEvent<(item: DownloadItem) => void>;
+  cancel(id: number): Promise<void>;
+  erase(query: { id: number }): Promise<number[]>;
+}
+
+export interface DownloadsSafetyNetDeps {
+  offer: (params: CaptureOfferParams, opts?: { timeoutMs?: number }) => Promise<CaptureOfferResult>;
+  downloads: DownloadsApiLike;
+  getCookies: (url: string) => Promise<CookieRecord[]>;
+  getRules: () => CaptureRules;
+  /** True when the header hook already offered this URL. */
+  wasOffered?: (url: string) => boolean;
+  onOffered?: (url: string) => void;
+  origin?: string;
+  budgetMs?: number;
+}
+
+/** Why the safety net did or did not act on a created download — for the popup diagnostics. */
+export type SafetyNetOutcome =
+  | 'taken' // offered and the daemon took it; Firefox's copy was cancelled + erased
+  | 'offer_declined' // offered, daemon replied ignore
+  | 'error' // fail-open: something threw, Firefox keeps the download
+  | 'capture_disabled'
+  | 'blob_or_data'
+  | 'excluded_host'
+  | 'already_offered'
+  | 'already_settled'
+  | 'no_rule_matched';
+
+type VetoOutcome = Exclude<SafetyNetOutcome, 'taken' | 'offer_declined' | 'error'>;
+
+const BUDGET_MS = 750;
+
+export class DownloadsSafetyNet {
+  private readonly budgetMs: number;
+  private bound?: (item: DownloadItem) => void;
+  private attachedTo?: DownloadsApiLike;
+
+  constructor(private readonly deps: DownloadsSafetyNetDeps) {
+    this.budgetMs = deps.budgetMs ?? BUDGET_MS;
+  }
+
+  attach(downloads: DownloadsApiLike): void {
+    if (this.attachedTo) throw new Error('DownloadsSafetyNet is already attached');
+    this.attachedTo = downloads;
+    this.bound = (item) => void this.handle(item);
+    downloads.onCreated.addListener(this.bound);
+  }
+
+  detach(): void {
+    if (this.attachedTo && this.bound) this.attachedTo.onCreated.removeListener(this.bound);
+    this.attachedTo = undefined;
+    this.bound = undefined;
+  }
+
+  /** Never throws. Returns what it did, for diagnostics/tests. */
+  async handle(item: DownloadItem): Promise<SafetyNetOutcome> {
+    try {
+      const url = effectiveUrl(item);
+      const decision = this.decide(item, url);
+      if (!decision.capture) return decision.reason;
+
+      let cookies: Cookie[] = [];
+      try {
+        cookies = toWireCookies(await this.deps.getCookies(url));
+      } catch {
+        cookies = [];
+      }
+
+      const params: CaptureOfferParams = {
+        url,
+        method: 'GET', // onCreated does not expose the method, and a POST body can't be replayed
+        tabUrl: item.referrer ?? '',
+        cookies,
+        contentType: item.mime ?? null,
+        contentLength: sizeOf(item),
+        filename: basenameOf(item.filename) ?? guessFilename(url, undefined),
+        referrer: item.referrer ?? null,
+        origin: this.deps.origin ?? null,
+      };
+
+      this.deps.onOffered?.(url);
+      const result = await this.deps.offer(params, { timeoutMs: this.budgetMs });
+      if (result.action !== 'take') return 'offer_declined';
+
+      // The daemon owns it now — retire Firefox's copy. Both best-effort.
+      try {
+        await this.deps.downloads.cancel(item.id);
+      } catch {
+        /* already complete or gone */
+      }
+      try {
+        await this.deps.downloads.erase({ id: item.id });
+      } catch {
+        /* nothing to erase */
+      }
+      return 'taken';
+    } catch {
+      return 'error'; // fail open: Firefox keeps the download
+    }
+  }
+
+  private decide(item: DownloadItem, url: string): { capture: true } | { capture: false; reason: VetoOutcome } {
+    const veto = (reason: VetoOutcome) => ({ capture: false as const, reason });
+    const rules = this.deps.getRules();
+    if (!rules.enabled) return veto('capture_disabled');
+    if (/^(blob:|data:)/i.test(url)) return veto('blob_or_data');
+    if (item.state === 'complete' || item.state === 'interrupted') return veto('already_settled');
+    if (this.deps.wasOffered?.(url)) return veto('already_offered');
+
+    const host = hostOf(url);
+    if (host && hostExcluded(host, rules.excludedHosts)) return veto('excluded_host');
+
+    const ext = filenameExtension(basenameOf(item.filename) ?? url);
+    if (ext && rules.monitoredExtensions.includes(ext)) return { capture: true };
+    if (item.mime && rules.monitoredMimeTypes.includes(item.mime.toLowerCase())) return { capture: true };
+
+    const size = sizeOf(item);
+    if (size !== null && size > rules.minSizeBytes) return { capture: true };
+
+    return veto('no_rule_matched');
+  }
+}
+
+// --- helpers ----------------------------------------------------------------------
+
+function effectiveUrl(item: DownloadItem): string {
+  return item.finalUrl && item.finalUrl.length > 0 ? item.finalUrl : item.url;
+}
+
+function sizeOf(item: DownloadItem): number | null {
+  for (const v of [item.totalBytes, item.fileSize]) {
+    if (typeof v === 'number' && v > 0) return v;
+  }
+  return null;
+}
+
+function basenameOf(filename: string | undefined): string | undefined {
+  if (!filename) return undefined;
+  const base = filename.split(/[\\/]/).pop();
+  return base && base.length > 0 ? base : undefined;
+}
+
+function hostOf(url: string): string {
+  try {
+    return new URL(url).hostname;
+  } catch {
+    return '';
+  }
+}

extension/src/background/capture/index.ts

@@ -0,0 +1,232 @@
+// The blocking onHeadersReceived hook.
+//
+// For a response that shouldCapture() likes: gather cookies, offer it to the daemon with
+// a hard 750 ms budget, and cancel the browser's own download ONLY on an explicit
+// {action:"take"}. Everything else — shouldCapture says no, the daemon is down / slow /
+// erroring, cookies fail, anything throws — resolves to {} and Firefox downloads
+// normally. Fail-open is not a fallback path here; it is the default every branch returns
+// to. tests/capture/hook.test.ts pins that.
+
+import type {
+  CaptureOfferParams,
+  CaptureOfferResult,
+  CaptureRules,
+  Cookie,
+} from '../../shared/protocol/index.js';
+
+import { normalizeHeaders } from './headers.js';
+import type { HeaderStash } from './headers.js';
+import { filenameExtension, shouldCapture, type CaptureCandidate, type ResourceType } from './rules.js';
+
+const BUDGET_MS = 750; // docs/05 §2 and METHODS['capture.offer'].deadlineMs
+const PROCEED: BlockingResponse = {};
+const CANCEL: BlockingResponse = { cancel: true };
+
+export interface BlockingResponse {
+  cancel?: boolean;
+}
+
+export interface OnHeadersReceivedDetails {
+  requestId: string;
+  url: string;
+  method: string;
+  type: ResourceType;
+  statusCode: number;
+  tabId: number;
+  responseHeaders?: { name: string; value?: string }[];
+  documentUrl?: string | null;
+  originUrl?: string | null;
+}
+
+interface WebRequestEvent<L extends (...a: never[]) => void> {
+  addListener(listener: L, filter: { urls: string[] }, extraInfoSpec?: string[]): void;
+  removeListener(listener: L): void;
+}
+
+export interface HeadersReceivedWebRequest {
+  onHeadersReceived: WebRequestEvent<
+    (d: OnHeadersReceivedDetails) => BlockingResponse | Promise<BlockingResponse>
+  >;
+}
+
+/** A browser cookie, as `browser.cookies.getAll` returns it (superset of the wire type). */
+export interface CookieRecord {
+  name: string;
+  value: string;
+  domain?: string;
+  path?: string;
+  secure?: boolean;
+  httpOnly?: boolean;
+}
+
+export interface CaptureHookDeps {
+  /** Usually `(p, o) => transport.call('capture.offer', p, o)`. */
+  offer: (params: CaptureOfferParams, opts?: { timeoutMs?: number }) => Promise<CaptureOfferResult>;
+  stash: Pick<HeaderStash, 'take' | 'peek'>;
+  getCookies: (url: string) => Promise<CookieRecord[]>;
+  /** A synchronous snapshot of the daemon's capture policy (mirrored via capture.getRules). */
+  getRules: () => CaptureRules;
+  /** Whether the user held the bypass modifier for the click behind this request. */
+  bypassHeld?: (details: OnHeadersReceivedDetails) => boolean;
+  /** Called with the URL just before an offer is made, so the downloads.onCreated safety
+   *  net can tell this request has already been handled here. */
+  onOffered?: (url: string) => void;
+  /** moz-extension://<uuid>, for CaptureOfferParams.origin. */
+  origin?: string;
+  budgetMs?: number;
+}
+
+const ALL_URLS = '<all_urls>';
+
+export class CaptureHook {
+  private readonly budgetMs: number;
+  private bound?: (d: OnHeadersReceivedDetails) => Promise<BlockingResponse>;
+  private attachedTo?: HeadersReceivedWebRequest;
+
+  constructor(private readonly deps: CaptureHookDeps) {
+    this.budgetMs = deps.budgetMs ?? BUDGET_MS;
+  }
+
+  /** The listener. Always resolves within the budget to {} or {cancel:true}; never rejects. */
+  handle = (details: OnHeadersReceivedDetails): Promise<BlockingResponse> => {
+    return this.withinBudget(this.decide(details));
+  };
+
+  attach(webRequest: HeadersReceivedWebRequest): void {
+    if (this.attachedTo) throw new Error('CaptureHook is already attached');
+    this.attachedTo = webRequest;
+    this.bound = this.handle;
+    webRequest.onHeadersReceived.addListener(this.bound, { urls: [ALL_URLS] }, [
+      'blocking',
+      'responseHeaders',
+    ]);
+  }
+
+  detach(): void {
+    if (this.attachedTo && this.bound) {
+      this.attachedTo.onHeadersReceived.removeListener(this.bound);
+    }
+    this.attachedTo = undefined;
+    this.bound = undefined;
+  }
+
+  private withinBudget(work: Promise<BlockingResponse>): Promise<BlockingResponse> {
+    return new Promise<BlockingResponse>((resolve) => {
+      let settled = false;
+      const done = (value: BlockingResponse): void => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        resolve(value);
+      };
+      const timer = setTimeout(() => done(PROCEED), this.budgetMs);
+      (timer as { unref?: () => void }).unref?.();
+      work.then(done, () => done(PROCEED));
+    });
+  }
+
+  private async decide(details: OnHeadersReceivedDetails): Promise<BlockingResponse> {
+    try {
+      const rules = this.deps.getRules();
+      const responseHeaders = normalizeHeaders(details.responseHeaders);
+      const stashed = this.stashPeek(details.requestId);
+
+      const candidate: CaptureCandidate = {
+        url: details.url,
+        method: details.method,
+        statusCode: details.statusCode,
+        type: details.type,
+        responseHeaders,
+        requestHeaders: stashed?.headers ?? {},
+        documentUrl: details.documentUrl ?? details.originUrl ?? null,
+        bypassHeld: this.deps.bypassHeld?.(details) ?? false,
+      };
+
+      if (!shouldCapture(candidate, rules).capture) return PROCEED;
+
+      // We are acting on this request now — take the stash entry.
+      const taken = this.deps.stash.take(details.requestId);
+      const requestHeaders = taken?.headers ?? candidate.requestHeaders;
+
+      let cookies: Cookie[] = [];
+      try {
+        cookies = toWireCookies(await this.deps.getCookies(details.url));
+      } catch {
+        cookies = []; // best-effort; still worth offering
+      }
+
+      const params: CaptureOfferParams = {
+        url: details.url,
+        method: candidate.method.toUpperCase() === 'POST' ? 'POST' : 'GET',
+        tabUrl: candidate.documentUrl ?? '',
+        headers: requestHeaders,
+        cookies,
+        contentType: responseHeaders['content-type'] ?? null,
+        contentLength: intOrNull(responseHeaders['content-length']),
+        contentDisposition: responseHeaders['content-disposition'] ?? null,
+        filename: guessFilename(details.url, responseHeaders['content-disposition']),
+        referrer: requestHeaders['referer'] ?? null,
+        origin: this.deps.origin ?? null,
+        requestId: details.requestId,
+      };
+
+      this.deps.onOffered?.(details.url);
+      const result = await this.deps.offer(params, { timeoutMs: this.budgetMs });
+      return result.action === 'take' ? CANCEL : PROCEED;
+    } catch {
+      return PROCEED; // fail open on anything at all
+    }
+  }
+
+  private stashPeek(requestId: string) {
+    try {
+      return this.deps.stash.peek(requestId);
+    } catch {
+      return undefined;
+    }
+  }
+}
+
+// --- helpers ----------------------------------------------------------------------
+
+export function toWireCookies(records: CookieRecord[]): Cookie[] {
+  return records.map((c) => {
+    const out: Cookie = { name: c.name, value: c.value };
+    if (c.domain !== undefined) out.domain = c.domain;
+    if (c.path !== undefined) out.path = c.path;
+    if (c.secure !== undefined) out.secure = c.secure;
+    if (c.httpOnly !== undefined) out.httpOnly = c.httpOnly;
+    return out;
+  });
+}
+
+function intOrNull(value: string | undefined): number | null {
+  if (value === undefined) return null;
+  const n = Number(value);
+  return Number.isFinite(n) ? n : null;
+}
+
+/** RFC 6266 filename, falling back to the URL's last path segment. */
+export function guessFilename(url: string, disposition: string | undefined): string | null {
+  if (disposition) {
+    const star = /filename\*\s*=\s*(?:[^']*'[^']*')?([^;]+)/i.exec(disposition);
+    if (star?.[1]) {
+      try {
+        return decodeURIComponent(star[1].trim().replace(/^"|"$/g, '')) || null;
+      } catch {
+        /* fall through */
+      }
+    }
+    const plain = /filename\s*=\s*"?([^";]+)"?/i.exec(disposition);
+    if (plain?.[1]) return plain[1].trim() || null;
+  }
+  try {
+    const path = new URL(url).pathname;
+    const base = decodeURIComponent(path.slice(path.lastIndexOf('/') + 1));
+    if (base) return base;
+  } catch {
+    /* not a parseable URL */
+  }
+  const ext = filenameExtension(url);
+  return ext ? `download.${ext}` : null;
+}

extension/src/background/capture/offered-urls.ts

@@ -0,0 +1,51 @@
+// A short-lived record of URLs the header hook has already offered to the daemon, so the
+// downloads.onCreated safety net does not offer the same thing a second time.
+//
+// Bounded and time-capped for the same reason the header stash is (capture/headers.ts):
+// this sees a URL for every capture attempt and must never grow without bound.
+
+export interface OfferedUrlsOptions {
+  /** Entries older than this stop counting as "recently offered". Default 15 s. */
+  ttlMs?: number;
+  /** Hard cap on tracked URLs; oldest evicted past it. Default 256. */
+  maxEntries?: number;
+  now?: () => number;
+}
+
+export class OfferedUrls {
+  private readonly ttlMs: number;
+  private readonly maxEntries: number;
+  private readonly now: () => number;
+  /** url -> timestamp, insertion-ordered so the first key is the oldest. */
+  private readonly seen = new Map<string, number>();
+
+  constructor(opts: OfferedUrlsOptions = {}) {
+    this.ttlMs = opts.ttlMs ?? 15_000;
+    this.maxEntries = opts.maxEntries ?? 256;
+    this.now = opts.now ?? Date.now;
+  }
+
+  mark(url: string): void {
+    this.seen.delete(url);
+    this.seen.set(url, this.now());
+    while (this.seen.size > this.maxEntries) {
+      const oldest = this.seen.keys().next().value;
+      if (oldest === undefined) break;
+      this.seen.delete(oldest);
+    }
+  }
+
+  has(url: string): boolean {
+    const at = this.seen.get(url);
+    if (at === undefined) return false;
+    if (this.now() - at > this.ttlMs) {
+      this.seen.delete(url);
+      return false;
+    }
+    return true;
+  }
+
+  get size(): number {
+    return this.seen.size;
+  }
+}

extension/src/background/capture/rules.ts

@@ -63,6 +63,19 @@ export interface CaptureDecision {
   reason: CaptureReason;
 }
 
+/**
+ * What shouldCapture() runs against before the first capture.getRules has been mirrored
+ * from the daemon. `enabled: false` — we intercept nothing until we know the real policy.
+ */
+export const DEFAULT_CAPTURE_RULES: CaptureRules = {
+  enabled: false,
+  monitoredExtensions: [],
+  monitoredMimeTypes: [],
+  minSizeBytes: 1024 * 1024,
+  excludedHosts: [],
+  rulesVersion: 0,
+};
+
 const RENDERABLE_TYPES = new Set([
   'text/html',
   'application/xhtml+xml',

extension/src/background/context-menus.ts

@@ -0,0 +1,123 @@
+// Right-click and keyboard entry points.
+//
+// docs/05 §3: "Download with Velox" on a link or a media element hands that one URL to
+// the daemon; a configurable command grabs the active tab's URL the same way. The
+// page/selection "Download all links…" item waits on the content-script link harvester
+// (build-order step 7) and is added there.
+//
+// These are explicit user requests, so they go straight to download.add — no
+// shouldCapture, no fail-open dance.
+
+import type { DownloadSpec } from '../shared/protocol/index.js';
+
+export const LINK_MENU_ID = 'velox-download-link';
+export const MEDIA_MENU_ID = 'velox-download-media';
+export const GRAB_TAB_COMMAND = 'velox-grab-current-tab';
+
+interface OnClickedInfo {
+  menuItemId: string | number;
+  linkUrl?: string;
+  srcUrl?: string;
+  pageUrl?: string;
+}
+
+interface Tab {
+  url?: string;
+  title?: string;
+}
+
+interface Listenable<A extends unknown[]> {
+  addListener(cb: (...args: A) => void): void;
+  removeListener(cb: (...args: A) => void): void;
+}
+
+export interface MenusLike {
+  create(props: {
+    id: string;
+    title: string;
+    contexts: string[];
+  }): void;
+  removeAll(): Promise<void> | void;
+  onClicked: Listenable<[OnClickedInfo, Tab | undefined]>;
+}
+
+export interface CommandsLike {
+  onCommand: Listenable<[string, Tab | undefined]>;
+}
+
+export interface TabsLike {
+  query(q: { active: true; currentWindow: true }): Promise<Tab[]>;
+}
+
+export interface ContextMenusDeps {
+  addDownload: (spec: DownloadSpec) => Promise<unknown>;
+  menus: MenusLike;
+  tabs: TabsLike;
+  commands?: CommandsLike;
+  /** Surface a failure to the user (a notification, usually). Optional. */
+  onError?: (message: string) => void;
+}
+
+export class ContextMenus {
+  private onClicked?: (info: OnClickedInfo, tab: Tab | undefined) => void;
+  private onCommand?: (name: string, tab: Tab | undefined) => void;
+
+  constructor(private readonly deps: ContextMenusDeps) {}
+
+  async register(): Promise<void> {
+    await this.deps.menus.removeAll();
+    this.deps.menus.create({ id: LINK_MENU_ID, title: 'Download with Velox', contexts: ['link'] });
+    this.deps.menus.create({
+      id: MEDIA_MENU_ID,
+      title: 'Download with Velox',
+      contexts: ['image', 'video', 'audio'],
+    });
+
+    this.onClicked = (info, tab) => void this.handleClick(info, tab);
+    this.deps.menus.onClicked.addListener(this.onClicked);
+
+    if (this.deps.commands) {
+      this.onCommand = (name, tab) => void this.handleCommand(name, tab);
+      this.deps.commands.onCommand.addListener(this.onCommand);
+    }
+  }
+
+  dispose(): void {
+    if (this.onClicked) this.deps.menus.onClicked.removeListener(this.onClicked);
+    if (this.onCommand && this.deps.commands) this.deps.commands.onCommand.removeListener(this.onCommand);
+    this.onClicked = undefined;
+    this.onCommand = undefined;
+  }
+
+  private async handleClick(info: OnClickedInfo, _tab: Tab | undefined): Promise<void> {
+    let url: string | undefined;
+    if (info.menuItemId === LINK_MENU_ID) url = info.linkUrl;
+    else if (info.menuItemId === MEDIA_MENU_ID) url = info.srcUrl;
+    else return;
+    await this.add(url, info.pageUrl);
+  }
+
+  private async handleCommand(name: string, tab: Tab | undefined): Promise<void> {
+    if (name !== GRAB_TAB_COMMAND) return;
+    const active = tab ?? (await this.deps.tabs.query({ active: true, currentWindow: true }))[0];
+    await this.add(active?.url, active?.url);
+  }
+
+  private async add(url: string | undefined, referrer: string | undefined): Promise<void> {
+    if (!url || !/^https?:/i.test(url)) {
+      this.deps.onError?.('Velox can only download http(s) links.');
+      return;
+    }
+    const spec: DownloadSpec = { url };
+    if (referrer) spec.referrer = referrer;
+    try {
+      await this.deps.addDownload(spec);
+    } catch (err) {
+      this.deps.onError?.(`Velox could not start the download: ${describe(err)}`);
+    }
+  }
+}
+
+function describe(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}

extension/src/background/index.ts

@@ -1,20 +1,95 @@
 // Background event-page entry.
 //
-// Brings the transport up and holds the single shared reference to it. Capture, the
-// popup relay, and context menus attach here as they land (docs/05 §6 build order).
+// Brings the transport up, mirrors the daemon's capture rules, and wires both capture
+// paths: the blocking onHeadersReceived hook and the downloads.onCreated safety net. The
+// popup relay and context menus attach here in later steps of the build order.
 
+import { DownloadsSafetyNet, type DownloadsApiLike } from './capture/downloads-api.js';
+import { HeaderStash, type WebRequestLike } from './capture/headers.js';
+import { CaptureHook, type HeadersReceivedWebRequest } from './capture/index.js';
+import { OfferedUrls } from './capture/offered-urls.js';
+import { DEFAULT_CAPTURE_RULES } from './capture/rules.js';
+import {
+  ContextMenus,
+  type CommandsLike,
+  type MenusLike,
+  type TabsLike,
+} from './context-menus.js';
 import { createTransport, type TransportStatus, type VeloxTransport } from './transport/index.js';
+import type { CaptureOfferParams, CaptureRules, DownloadSpec } from '../shared/protocol/index.js';
 
 let transport: VeloxTransport | undefined;
+let rules: CaptureRules = DEFAULT_CAPTURE_RULES;
+
+const EXTENSION_ORIGIN = new URL(browser.runtime.getURL('/')).origin;
+
+function mustTransport(): VeloxTransport {
+  if (!transport) throw new Error('transport not ready');
+  return transport;
+}
+
+const offer = (params: CaptureOfferParams, opts?: { timeoutMs?: number }) =>
+  mustTransport().call('capture.offer', params, opts);
+const getCookies = (url: string) => browser.cookies.getAll({ url });
+
+const offered = new OfferedUrls();
+const stash = new HeaderStash();
+
+const hook = new CaptureHook({
+  offer,
+  stash,
+  getCookies,
+  getRules: () => rules,
+  onOffered: (url) => offered.mark(url),
+  origin: EXTENSION_ORIGIN,
+});
+
+const safetyNet = new DownloadsSafetyNet({
+  offer,
+  downloads: browser.downloads as unknown as DownloadsApiLike,
+  getCookies,
+  getRules: () => rules,
+  wasOffered: (url) => offered.has(url),
+  onOffered: (url) => offered.mark(url),
+  origin: EXTENSION_ORIGIN,
+});
+
+const contextMenus = new ContextMenus({
+  addDownload: (spec: DownloadSpec) => mustTransport().call('download.add', spec),
+  menus: browser.contextMenus as unknown as MenusLike,
+  tabs: browser.tabs as unknown as TabsLike,
+  commands: browser.commands as unknown as CommandsLike,
+  onError: (message) => {
+    void browser.notifications.create({ type: 'basic', title: 'Velox', message });
+  },
+});
+
+async function refreshRules(): Promise<void> {
+  try {
+    rules = await mustTransport().call('capture.getRules', {});
+  } catch {
+    // Keep the last known rules; capture stays fail-open regardless (docs/05 §2).
+  }
+}
 
 function onTransportState(status: TransportStatus): void {
   const detail = status.fatal ?? (status.needsPairing ? 'needs pairing' : '');
   console.debug(`[velox] transport ${status.state}${detail ? ` — ${detail}` : ''}`);
+  if (status.state === 'connected') void refreshRules();
 }
 
 async function start(): Promise<void> {
+  stash.attach(browser.webRequest as unknown as WebRequestLike);
+  hook.attach(browser.webRequest as unknown as HeadersReceivedWebRequest);
+  safetyNet.attach(browser.downloads as unknown as DownloadsApiLike);
+  void contextMenus.register();
+
   transport = await createTransport();
   transport.onStateChange(onTransportState);
+  transport.on('event.settings.changed', (payload) => {
+    const keys = (payload as { keys?: string[] }).keys ?? [];
+    if (keys.some((k) => k.startsWith('capture.'))) void refreshRules();
+  });
   onTransportState(transport.status);
 }