Skip to content

The OSINT investigator's workbench. One case, one folder, every tool. Local-first: your media and your investigations never leave your machine.

JavaScript
50.4 KB
Raw Blame
/**
 * Background worker: the only place pixels are grabbed.
 *
 * Chrome runs this as an MV3 service worker, Firefox as an event page (the
 * manifest declares both) — so it is a classic script with no imports, no DOM,
 * and no in-memory state that matters: anything that must survive a worker
 * restart lives in storage.session.
 *
 * Every capture is one captureVisibleTab behind one explicit user action
 * (repo legal rails): the popup's buttons, or the Azimut app's own Capture
 * button relayed by bridge.js. Nothing here is schedulable or repeatable
 * without a fresh user gesture.
 */

const api = typeof browser !== "undefined" ? browser : chrome;

const APP_ORIGINS = ["http://127.0.0.1", "http://localhost"];
const isAppUrl = (url) => APP_ORIGINS.some((o) => url === o || url?.startsWith(o + ":") || url?.startsWith(o + "/"));

/**
 * Whether a tab is the paired Azimut, not merely something on localhost.
 *
 * The bridge runs on every loopback port, so a dev server or any other local page
 * can post to it. The routes that open tabs, capture the screen or stream case files
 * answer only the page served from the port this extension is paired with.
 * `localhost` and `127.0.0.1` are the same machine, so either name passes.
 */
async function isPairedApp(url) {
  if (!isAppUrl(url)) return false;
  const { backendUrl } = await settings();
  try {
    const tab = new URL(url);
    const app = new URL(backendUrl);
    return isAppUrl(app.origin) && tab.port === app.port && tab.protocol === app.protocol;
  } catch {
    return false;
  }
}

/**
 * Why a tab may not use the routes only the app may ask for, or null when it may.
 *
 * A loopback page on another port is most often this same Azimut, started while
 * another program held its port and moved to the next free one. "Not the app" would
 * leave the analyst nowhere, so the answer says what to change.
 */
async function notTheApp(tab) {
  if (!tab || !isAppUrl(tab.url)) return "not the Azimut app";
  if (await isPairedApp(tab.url)) return null;
  return `this extension is paired with another address. In its options, set the Azimut URL to ${new URL(tab.url).origin}`;
}

// Where the app's hand-offs may take a tab: the posting sites and the reverse image
// engines it offers. Anything else in a hand-off is refused, whoever asked.
const HANDOFF_HOSTS = new Set(["x.com", "bsky.app", "lens.google.com", "yandex.com", "www.bing.com", "tineye.com"]);
const handOffAllowed = (url) => {
  try {
    const parsed = new URL(url);
    return parsed.protocol === "https:" && HANDOFF_HOSTS.has(parsed.hostname);
  } catch {
    return false;
  }
};

function settings() {
  return api.storage.local
    .get({ backendUrl: "http://127.0.0.1:8477", token: "", lastCaseId: "" })
    .then((s) => ({ ...s, backendUrl: s.backendUrl.replace(/\/+$/, "") }));
}

function captureActiveTab(windowId) {
  // promise-form works on both browsers in MV3
  return api.tabs.captureVisibleTab(windowId, { format: "png" });
}

/** Crop a captured frame (dataURL) to a viewport-CSS-px rect. The scale is
 * measured (image width / viewport width), not assumed from devicePixelRatio,
 * so browser zoom can't silently shift the crop — same rule as the app.
 *
 * Returns the crop *and* that scale: the crop keeps the frame's own pixels, so
 * the file holds `scale` of them per CSS pixel, and a zoom describes CSS
 * pixels. Anything the app draws with a distance on it needs the ratio, or a
 * scale bar on a 2× screen states twice the ground it covers. */
async function cropDataUrl(dataUrl, rect, viewportW) {
  const blob = await (await fetch(dataUrl)).blob();
  const bmp = await createImageBitmap(blob);
  const scale = bmp.width / viewportW;
  const sx = Math.max(0, Math.round(rect.x * scale));
  const sy = Math.max(0, Math.round(rect.y * scale));
  const sw = Math.min(bmp.width - sx, Math.round(rect.w * scale));
  const sh = Math.min(bmp.height - sy, Math.round(rect.h * scale));
  if (sw < 8 || sh < 8) throw new Error("selection too small");
  const canvas = new OffscreenCanvas(sw, sh);
  canvas.getContext("2d").drawImage(bmp, sx, sy, sw, sh, 0, 0, sw, sh);
  return { blob: await canvas.convertToBlob({ type: "image/png" }), scale };
}

/** File one screenshot with the backend (POST /api/ingest/screenshot). */
async function ingest(blob, meta) {
  const { backendUrl, token } = await settings();
  if (!token) throw new Error("not paired. Open the extension options and paste the token from Azimut Settings");
  // Thin on purpose: image + URL is a complete capture — the app parses the
  // URL itself (site, coordinates, title, imagery date). Everything else here
  // is either the user's popup corrections or plain context.
  const form = new FormData();
  form.append("image", blob, "screenshot.png");
  form.append("url", meta.url);
  form.append("case_id", meta.caseId || "");
  if (meta.title) form.append("title", meta.title);
  for (const k of ["lat", "lon", "zoom", "bearing"]) {
    if (meta[k] !== null && meta[k] !== undefined && meta[k] !== "") form.append(k, String(meta[k]));
  }
  if (meta.marks) {
    form.append("scale_north", "true");
    form.append("device_scale", String(meta.deviceScale || 1));
  }
  form.append("captured_at", new Date().toISOString());
  form.append("extension", api.runtime.getManifest().version);
  let r;
  try {
    r = await fetch(`${backendUrl}/api/ingest/screenshot`, {
      method: "POST",
      headers: { "X-Azimut-Token": token },
      body: form,
    });
  } catch {
    throw new Error(`Azimut is not reachable at ${backendUrl}. Is the app running?`);
  }
  if (r.status === 401) throw new Error("pairing token rejected. Pair again in the extension options");
  if (!r.ok) throw new Error(`Azimut refused the capture (${r.status}): ${(await r.text()).slice(0, 200)}`);
  const body = await r.json();
  // Remember where this capture landed — including a freshly minted scratch
  // (body.case_id), so repeated captures reuse it instead of minting one each.
  if (body.case_id || meta.caseId) {
    api.storage.local.set({ lastCaseId: body.case_id || meta.caseId });
  }
  return body;
}

// --- post hand-off: fill a composer the app prepared ----------------------------
//
// The app never posts, and neither does this: the thread is typed into the site's
// own composer and left there. Everything below is a layer over the path that
// already worked (the app opens the intent page, the thread is on the clipboard),
// so every failure returns rather than throws a user into a dead end.
//
// There is one switch and it lives in Azimut (Settings → Publishing): the app
// asks or it does not, and this side has no opinion to add. A second box here
// would be two answers to one question, and the pair that disagrees is the one
// nobody can find.

/**
 * Put one case attachment into the composer page a slice at a time.
 *
 * `executeScript` still needs a serializable string, but the string is now one
 * 4 MB slice rather than the whole video. The page decodes each slice at once
 * and keeps only byte arrays for the final `File`, so a long clip answers to the
 * app's 512 MB hand-off ceiling rather than an extension-only 48 MB ceiling.
 * The page itself never fetches the local URL, which keeps this path independent
 * of X's and Bluesky's content-security policies.
 */
async function streamAttachment(target, backendUrl, token, caseId, path, id) {
  let offset = 0;
  while (true) {
    const part = await fileChunk(backendUrl, token, caseId, path, offset);
    await api.scripting.executeScript({
      target,
      world: "MAIN",
      func: (fileId, type, data) => {
        const thread = window.__AZIMUT_HANDOFF__;
        const file = thread?.posts
          ?.flatMap((post) => post.files ?? [])
          .find((candidate) => candidate.id === fileId);
        if (!file) throw new Error("handed-over file disappeared");
        const binary = atob(data);
        const bytes = new Uint8Array(binary.length);
        for (let i = 0; i < binary.length; i += 1) bytes[i] = binary.charCodeAt(i);
        file.type = type || file.type;
        file.parts.push(bytes);
      },
      args: [id, part.type, part.data],
    });
    if (part.next === null) return;
    if (part.next <= offset) throw new Error("Azimut returned an empty file slice");
    offset = part.next;
  }
}

/** Leave no partial file in the page when one of its slices was refused. */
async function discardAttachment(target, id) {
  await api.scripting.executeScript({
    target,
    world: "MAIN",
    func: (fileId) => {
      const thread = window.__AZIMUT_HANDOFF__;
      for (const post of thread?.posts ?? []) {
        post.files = (post.files ?? []).filter((file) => file.id !== fileId);
      }
    },
    args: [id],
  });
}

/** One case attachment, addressed. */
function fileUrl(backendUrl, caseId, path) {
  return (
    `${backendUrl}/api/ingest/file?case_id=${encodeURIComponent(caseId)}` +
    `&path=${encodeURIComponent(path)}`
  );
}

/** Bytes as base64, in bounded pieces that can cross an injection boundary. */
function encode(bytes) {
  let binary = "";
  const CHUNK = 0x8000; // fromCharCode takes an argument list: chunk it or blow the stack
  for (let i = 0; i < bytes.length; i += CHUNK) {
    binary += String.fromCharCode.apply(null, bytes.subarray(i, i + CHUNK));
  }
  return btoa(binary);
}

/** A small blob as base64. Large files go through `fileChunk` instead. */
async function base64(blob) {
  return encode(new Uint8Array(await blob.arrayBuffer()));
}

/** Resolve once the tab has finished loading, so the injection lands on a page. */
function tabLoaded(tabId, timeoutMs = 20000) {
  return new Promise((resolve) => {
    const done = () => {
      api.tabs.onUpdated.removeListener(onUpdated);
      clearTimeout(timer);
      resolve();
    };
    // Not an error path: the composer is an app that keeps loading after the
    // document does, and the injected script waits for it anyway.
    const timer = setTimeout(done, timeoutMs);
    function onUpdated(id, info) {
      if (id === tabId && info.status === "complete") done();
    }
    api.tabs.onUpdated.addListener(onUpdated);
  });
}

/**
 * Say yes or no, now, and do the work afterwards.
 *
 * The app is holding a click while it waits for this, and a browser only lets a
 * page open a tab for a few seconds after one. So the answer here has to be about
 * whether the hand-off is *taken* — one cheap check — and never about how it
 * went: opening a tab, waiting for a composer to mount and attaching six files is
 * tens of seconds, and waiting that long to say no would spend the click on
 * nothing and leave the analyst pressing a dead button.
 *
 * Everything after the answer reports itself through notifications.
 */
async function handOff(payload) {
  const { backendUrl, token } = await settings();
  if (!token) throw new Error("not paired");
  if (!handOffAllowed(payload.url)) throw new Error("not a site Azimut posts to");
  fillComposer(payload, backendUrl, token).catch((e) =>
    notify("Azimut hand-off", `${e.message} The thread is on your clipboard.`)
  );
  return { ok: true, accepted: true };
}

async function fillComposer(payload, backendUrl, token) {
  const tab = await api.tabs.create({ url: payload.url, active: true });
  await tabLoaded(tab.id);
  // Both injections run in the page's own world, which is the only place a
  // composer accepts what we make (see handoff.js). Nothing over there can call
  // an extension API, so the thread goes in on a global, its file parts follow,
  // and the report comes back as the script's return value.
  const target = { tabId: tab.id };
  const plans = [];
  const posts = (payload.posts ?? []).map((post, postIndex) => ({
    text: post.text ?? "",
    files: (post.files ?? []).map((path, fileIndex) => {
      const id = `${postIndex}:${fileIndex}`;
      plans.push({ id, path });
      return {
        id,
        name: path.split("/").pop(),
        type: "application/octet-stream",
        parts: [],
      };
    }),
  }));
  await api.scripting.executeScript({
    target,
    world: "MAIN",
    func: (thread) => {
      window.__AZIMUT_HANDOFF__ = thread;
    },
    args: [{ posts }],
  });

  let skipped = 0;
  for (const plan of plans) {
    try {
      await streamAttachment(target, backendUrl, token, payload.caseId, plan.path, plan.id);
    } catch {
      skipped += 1;
      await discardAttachment(target, plan.id).catch(() => {});
    }
  }
  if (skipped) {
    notify(
      "Azimut hand-off",
      `${skipped} file${skipped > 1 ? "s" : ""} could not be handed over. Attach ${skipped > 1 ? "them" : "it"} from the case.`
    );
  }

  const [done] = await api.scripting.executeScript({
    target,
    world: "MAIN",
    files: ["handoff.js"],
  });
  if (done?.result?.error) {
    notify("Azimut hand-off", `${done.result.error} The thread is on your clipboard.`);
  }
}

// --- reverse hand-off: give one prepared image to a reverse-image engine --------
//
// Reverse Search's engine buttons, when the app asks. The same shape as the
// composer above — the app is answered at once and the work reports itself
// through notifications — with one difference that is worth saying out loud:
// **these pages search as soon as they hold a picture.** The composer is filled
// and left; an engine is asked. Both are one press of one button in the app, and
// neither happens without it.
//
// The bytes arrive from the app rather than being fetched from it: what Reverse
// Search hands over is a frame off a canvas — a video still, adjustments baked
// in — which exists nowhere on disk to be read back.

/** The largest image this will carry into a page, in base64 characters.
 *
 *  A ceiling the app applies first (lib/reverseSearch.js) and this one re-checks,
 *  because a message that big is a worker holding tens of megabytes to no end:
 *  every one of these engines refuses the upload long before this. */
const MAX_REVERSE_DATA = 28 * 1024 * 1024;

async function handOffReverse(payload) {
  const image = payload.image ?? {};
  if (!image.data) throw new Error("no image");
  if (image.data.length > MAX_REVERSE_DATA) throw new Error("that image is too large to hand over");
  if (!payload.url) throw new Error("no engine");
  if (!handOffAllowed(payload.url)) throw new Error("not an engine Azimut searches with");
  fillEngine(payload.url, image).catch((e) => {
    if (!LEFT.test(e.message || "")) trouble(e.message);
  });
  return { ok: true, accepted: true };
}

/**
 * Say what went wrong in a sentence the analyst can act on.
 *
 * A browser grants the hosts a manifest declares **when it loads the copy**, and
 * an extension cannot ask for one later. So a copy loaded before this feature
 * existed refuses the injection with a sentence about manifests, which reads
 * like a bug in the app and is fixed by one reload. Everything else is passed
 * through as it came.
 */
function trouble(message) {
  const stale = /permission|access contents of the page/i.test(message);
  notify(
    "Azimut reverse search",
    stale
      ? "This extension was loaded before Azimut knew these engines. Reload it in your browser, then press the engine again. The image is on your clipboard."
      : `${message} The image is on your clipboard.`
  );
}

/** A page that left rather than a page that refused.
 *
 *  An engine that takes the picture searches with it, and the injected script
 *  goes with the document it was running in — so "the frame is gone" is what
 *  success looks like from here, and it arrives as an error. Reporting it would
 *  put a failure notice on top of the results the analyst asked for. */
const LEFT = /frame|no longer exists|destroyed|navigat|context invalidated/i;

async function fillEngine(url, image) {
  const tab = await api.tabs.create({ url, active: true });
  await tabLoaded(tab.id);
  // Both injections run in the page's own world, which is the only place an
  // uploader takes what we make (see reverse.js). Nothing over there can call an
  // extension API, so the image goes in on a global and the report comes back as
  // the script's return value.
  const target = { tabId: tab.id };
  await api.scripting.executeScript({
    target,
    world: "MAIN",
    func: (handed) => {
      window.__AZIMUT_REVERSE__ = handed;
    },
    args: [{ image }],
  });
  const [done] = await api.scripting.executeScript({
    target,
    world: "MAIN",
    files: ["reverse.js"],
  });
  if (done?.result?.error) trouble(done.result.error);
}

// --- the folder this copy was loaded from ---------------------------------------
//
// The app owns that folder (engine/extinstall.py) and stamps install.json into
// it, so the question "is the extension this browser loaded the copy I control"
// has an answer. Read from the background rather than the content script: in
// Chrome a content-script fetch answers to the *page's* origin, so reading an own
// resource that isn't web-accessible would be refused. It is deliberately not
// web-accessible — no page has business reading it.

/** The stamp as it was when this extension last loaded.
 *
 * Cached in storage.session on purpose, and that is the whole design: a fresh
 * read of install.json reports the *folder*, which the app has already rewritten
 * by the time it asks, so it would answer "up to date" whether or not this code
 * ever restarted. storage.session survives a worker eviction and is cleared when
 * the extension unloads, so what it holds is what the running code was installed
 * from — the one claim worth verifying an update against.
 *
 * The manifest version can't play that role: within a development cycle it is
 * already the app's own version and never moves when the bytes do.
 */
let loadedStampPromise = null;

function loadedStamp() {
  if (!loadedStampPromise) loadedStampPromise = readLoadedStamp();
  return loadedStampPromise;
}

async function readLoadedStamp() {
  const seeded = await api.storage.session.get("loadedStamp");
  if (seeded.loadedStamp !== undefined) return seeded.loadedStamp;
  let stamp = null;
  try {
    const r = await fetch(api.runtime.getURL("install.json"));
    if (r.ok) stamp = await r.json();
  } catch {
    // No stamp: loaded from a folder the app doesn't own, which is a state the
    // app reports rather than an error.
  }
  // `null` is a real answer and has to be stored as one, or every later call
  // re-reads a file that isn't there.
  await api.storage.session.set({ loadedStamp: stamp });
  return stamp;
}

/** How the browser installed this copy: "development" for a folder or a
 * temporary add-on, "normal" for a packaged one it manages itself.
 *
 * Firefox refuses an unsigned extension outside the developer channels, so a
 * permanent Firefox install is a signed XPI — sealed, with no install.json and
 * nothing the app could rewrite. Without this, such a copy looks exactly like an
 * old manual unzip, and Settings would tell the analyst to remove the only
 * install their browser will keep.
 *
 * `management.getSelf` needs no permission. Null where it is unavailable, which
 * reads as "cannot tell" rather than as a claim.
 */
async function installType() {
  try {
    return (await api.management.getSelf()).installType ?? null;
  } catch {
    return null;
  }
}

/** Re-attach the bridge to the app's own tabs.
 *
 * Neither browser re-injects content scripts after an extension reloads, so
 * without this the app's tab keeps an orphaned bridge and the analyst is told to
 * reload the page — a manual step in the feature whose point is removing one.
 * Runs on every worker start; injecting twice is handled on the bridge side.
 */
async function reattachBridge() {
  try {
    const tabs = await api.tabs.query({ url: APP_ORIGINS.map((o) => `${o}/*`) });
    for (const tab of tabs) {
      api.scripting
        .executeScript({ target: { tabId: tab.id }, files: ["bridge.js"] })
        .catch(() => {});
    }
  } catch {
    // A tab we may not inject is the pre-existing "reload this tab" case.
  }
}

function notify(title, message) {
  // fire-and-forget: a failed toast must never fail a filed capture
  try {
    api.notifications.create({
      type: "basic",
      iconUrl: api.runtime.getURL("icons/icon128.png"),
      title,
      message: String(message).slice(0, 300),
    });
  } catch {
    /* notifications are best-effort */
  }
}

// --- the map tools -------------------------------------------------------------
//
// The panel runs as a content script on someone else's map, so its own fetch
// would carry that site's origin — which the app refuses, exactly as it should
// (`server.py`, the local guard). Every call it makes is relayed here instead
// and goes out as the extension.
//
// The allowlist is the point. This worker holds the pairing token, and a relay
// that forwarded any path would hand the whole ingest surface to whatever ends
// up running in a map tab. These are the routes the four tools need and nothing
// else. The nudge stream is not among them and never should be: it is one answer
// that never ends, and it is read below rather than relayed.
const MAP_ROUTES = new Set([
  "/api/ingest/ping",
  "/api/ingest/cases",
  "/api/ingest/parse",
  "/api/ingest/saved",
  "/api/ingest/sky",
  "/api/ingest/grids",
  "/api/ingest/grid",
  "/api/ingest/grid/marks",
  "/api/ingest/place",
  "/api/ingest/media",
  "/api/ingest/probe",
  "/api/ingest/firms/sensors",
]);

// …and the ones that answer with bytes. Separate because the relay above parses
// what comes back as JSON, and because a route that hands over a picture is
// worth listing where it can be seen rather than inferred from a content type.
const MAP_IMAGE_ROUTES = new Set(["/api/ingest/firms"]);

//. Injected in this order: each one reads the globals the ones before it left.
const MAP_FILES = [
  "mapmath.js",
  "maptheme.js",
  "maptools.js",
  "mapdraw.js",
  "mapref.js",
  "maplink.js",
  "mapoverlay.js",
];

async function mapApi(msg) {
  if (!MAP_ROUTES.has(msg.path)) throw new Error(`the map tools may not call ${msg.path}`);
  const { backendUrl, token } = await settings();
  if (!token) throw new Error("not paired. Open the extension options and paste the token from Azimut Settings");

  const url = new URL(backendUrl + msg.path);
  for (const [key, value] of Object.entries(msg.query || {})) {
    if (value !== undefined && value !== null && value !== "") url.searchParams.set(key, value);
  }
  const init = { method: msg.method || "GET", headers: { "X-Azimut-Token": token } };
  if (msg.body && msg.form) {
    const form = new FormData();
    for (const [key, value] of Object.entries(msg.body)) {
      if (value !== undefined && value !== null) form.append(key, String(value));
    }
    init.body = form;
  } else if (msg.body) {
    init.headers["Content-Type"] = "application/json";
    init.body = JSON.stringify(msg.body);
  }

  let r;
  try {
    r = await fetch(url, init);
  } catch {
    throw new Error("Azimut is not answering. Is the app running?");
  }
  if (r.status === 401) throw new Error("pairing token rejected. Pair again in the extension options");
  const text = await r.text();
  if (!r.ok) {
    let detail = text;
    try {
      detail = JSON.parse(text).detail ?? text;
    } catch {
      // a proxy or a crash can answer with something that is not JSON
    }
    throw new Error(typeof detail === "string" ? detail : `the app refused: ${r.status}`);
  }
  return text ? JSON.parse(text) : null;
}

/**
 * A picture the app draws for the panel — today, NASA FIRMS over the view.
 *
 * Two reasons it is not `mapApi`: what comes back is bytes rather than JSON,
 * and it is handed over as a data URL because a content script cannot hold the
 * app's blob URL. The refusal is still read as the app's own sentence, since
 * FIRMS says exactly what is wrong with a key and that is worth repeating.
 */
async function mapImage(msg) {
  if (!MAP_IMAGE_ROUTES.has(msg.path)) throw new Error(`the map tools may not call ${msg.path}`);
  const { backendUrl, token } = await settings();
  if (!token) throw new Error("not paired. Open the extension options and paste the token from Azimut Settings");

  const url = new URL(backendUrl + msg.path);
  for (const [key, value] of Object.entries(msg.query || {})) {
    if (value !== undefined && value !== null && value !== "") url.searchParams.set(key, value);
  }
  let r;
  try {
    r = await fetch(url, { headers: { "X-Azimut-Token": token } });
  } catch {
    throw new Error("Azimut is not answering. Is the app running?");
  }
  if (!r.ok) throw new Error(await refusal(r));
  const blob = await r.blob();
  return `data:${blob.type || "image/png"};base64,${await base64(blob)}`;
}

/** How much of a file crosses in one message.
 *
 *  The whole point of the number: base64 of *this* is the biggest string either
 *  side ever holds, whatever the file weighs. A phone's clip of a street is
 *  hundreds of megabytes; both the composer and a map reference need the file
 *  without making the file itself the unit. */
const FILE_CHUNK_BYTES = 4 * 1024 * 1024;

/** The end and the total of a `Content-Range`, or null when the app answered with
 *  the whole file — an unranged 200, which is what a small file gets. */
function ranged(header) {
  const m = /^bytes (\d+)-(\d+)\/(\d+)$/.exec(String(header || ""));
  return m ? { end: Number(m[2]), total: Number(m[3]) } : null;
}

/**
 * One slice of one of the case's files, for a composer or reference window.
 *
 * Not `mapApi`: that one parses what comes back as JSON, and this is bytes. The
 * route is written in rather than allowlisted — the panel may ask for a file
 * from the case it has open and for nothing else, and the app's own fence
 * (`api/ingest.py`, ``handoff_file``) is what says which files those are.
 *
 * `Range` is what `FileResponse` already serves, so nothing over there had to be
 * built for this: the consumer asks again from `next` until `next` is null and
 * glues the pieces into one file. A slice short of the chunk size is not the
 * signal — a file whose length divides evenly would end on a 416 — so the total
 * in `Content-Range` is.
 */
async function fileChunk(backendUrl, token, caseId, path, offset = 0) {
  const start = Number(offset) || 0;
  let r;
  try {
    r = await fetch(fileUrl(backendUrl, caseId, path), {
      headers: {
        "X-Azimut-Token": token,
        Range: `bytes=${start}-${start + FILE_CHUNK_BYTES - 1}`,
      },
    });
  } catch {
    throw new Error("Azimut is not answering. Is the app running?");
  }
  if (!r.ok) throw new Error(await refusal(r));
  const blob = await r.blob();
  const bytes = new Uint8Array(await blob.arrayBuffer());
  const read = start + bytes.length;
  // No `Content-Range` means the app ignored the ask and sent everything, which
  // is a whole file in one message rather than a broken one.
  const total = ranged(r.headers?.get?.("Content-Range"))?.total ?? read;
  return {
    type: blob.type || "application/octet-stream",
    data: encode(bytes),
    next: read < total ? read : null,
    total,
  };
}

async function mapFile(caseId, path, offset = 0) {
  const { backendUrl, token } = await settings();
  if (!token) throw new Error("not paired. Open the extension options and paste the token from Azimut Settings");
  if (!caseId) throw new Error("no case open");
  return fileChunk(backendUrl, token, caseId, path, offset);
}

/** Why the app would not hand a file over, in its own words where it gave any —
 *  the size ceiling is stated there, and a second copy of the number here is a
 *  number that goes stale. */
async function refusal(r) {
  if (r.status === 401) return "pairing token rejected. Pair again in the extension options";
  let detail = "";
  try {
    detail = JSON.parse(await r.text()).detail;
  } catch {
    // a proxy or a crash can answer with something that is not JSON
  }
  return typeof detail === "string" && detail ? detail : `the app refused that file (${r.status})`;
}

/** How long the panel is given to say it has left the frame. */
const PANEL_ANSWER_MS = 500;

/**
 * Take the panel out of the frame, grab, put it back.
 *
 * `captureVisibleTab` photographs the page as it is composited, and the map
 * tools panel — reference windows and all — is on it. A tab with no panel
 * open does not answer, which is not an error, and the panel is shown again
 * whatever the grab did.
 */
async function withoutPanel(tabId, grab) {
  const tell = async (hide) => {
    try {
      // The panel applies it on receipt and only *answers* a frame later, so a
      // wait that runs out costs a frame of certainty and never a hidden panel.
      // Unbounded, it would be a Capture button that spins for good.
      await Promise.race([
        api.tabs.sendMessage(tabId, { type: "map-chrome", hide }),
        new Promise((resolve) => setTimeout(resolve, PANEL_ANSWER_MS)),
      ]);
    } catch {
      // no panel on this tab to answer, which is the usual case
    }
  };
  await tell(true);
  try {
    return await grab();
  } finally {
    await tell(false);
  }
}

// --- the nudge stream ----------------------------------------------------------
//
// A panel draws a case it is also being worked from elsewhere: the app's own map
// on one screen, this panel over a site's map on another, a second panel on a
// third. Every one of them writes to the same files, and before this each only
// ever saw what it had asked for — a point filed in the app appeared on a panel
// the next time it was opened, which is a page reload in a feature whose point is
// not needing one.
//
// So the app's own nudge channel is read here (`api/events.py`) and handed to the
// panels. Here rather than in each panel, for three reasons: a content script's
// fetch carries the map site's origin, which the app's local guard refuses; it
// could not hold the pairing token if it wanted to; and ten tabs on one map would
// otherwise be ten streams for one bus.
//
// Not through `mapApi`: that relay parses what comes back as one JSON answer, and
// this response never ends.

const SYNC_PORT = "map-sync";
/** How long to wait before re-opening a stream that dropped, and the ceiling it
 *  backs off to. The app being restarted is the ordinary case, so the first
 *  retry is quick and a long outage costs one attempt a minute. */
const FIRST_RETRY_MS = 1000;
const MAX_RETRY_MS = 60000;

/** The panels listening, one port each. A port dies with its tab, which is what
 *  makes this the count of panels actually open. */
const panels = new Set();
let streamRun = 0; // generation: a retry from a stream that was stopped stands down
let streamAbort = null;
let pumping = false;

const pause = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

/**
 * One SSE frame as an event, or null.
 *
 * The bus writes `: ping` comments as keepalive and one `data:` line per event
 * (`api/events.py`). Anything else — a comment, a frame that is not our JSON — is
 * a nudge that never happened, and a missed nudge costs a refresh.
 */
function frameEvent(frame) {
  const data = frame
    .split("\n")
    .filter((line) => line.startsWith("data:"))
    .map((line) => line.slice(5).trim())
    .join("");
  if (!data) return null;
  try {
    return JSON.parse(data);
  } catch {
    return null;
  }
}

function fanOut(event) {
  for (const port of panels) {
    try {
      port.postMessage({ type: "app-event", event });
    } catch {
      // the tab went while this was in hand; its disconnect is already queued
    }
  }
}

/** Hold the stream open, handing every event to the panels, until it ends. */
async function readEvents(run) {
  const { backendUrl, token } = await settings();
  if (!token) throw new Error("not paired");
  const controller = new AbortController();
  streamAbort = controller;
  const r = await fetch(`${backendUrl}/api/ingest/events`, {
    headers: { "X-Azimut-Token": token },
    signal: controller.signal,
  });
  if (r.status === 401) throw new Error("pairing token rejected");
  if (!r.ok || !r.body) throw new Error(`the app refused the event stream (${r.status})`);
  const reader = r.body.getReader();
  const decoder = new TextDecoder();
  let buffer = "";
  while (run === streamRun) {
    const { value, done } = await reader.read();
    if (done) return;
    buffer += decoder.decode(value, { stream: true });
    // frames are separated by a blank line, and a chunk can hold part of one
    let cut = buffer.indexOf("\n\n");
    while (cut >= 0) {
      const event = frameEvent(buffer.slice(0, cut));
      buffer = buffer.slice(cut + 2);
      if (event) fanOut(event);
      cut = buffer.indexOf("\n\n");
    }
  }
}

/**
 * Keep a stream open while any panel is listening.
 *
 * Every failure here is the same failure — the app is not running, or not
 * running yet — and the answer to it is to try again later rather than to tell
 * anybody: the panel already says what it cannot reach, on the errand it was
 * asked to run. What it must not do is spin: hence the backoff, and the
 * generation check that stops a retry belonging to a stream nobody wants.
 */
async function pumpEvents() {
  if (pumping) return;
  pumping = true;
  const run = streamRun;
  let wait = FIRST_RETRY_MS;
  try {
    while (run === streamRun && panels.size) {
      try {
        await readEvents(run);
        wait = FIRST_RETRY_MS; // it was open once, so the app is there
      } catch {
        // not reachable, not paired, or refused — the retry is the whole answer
      }
      if (run !== streamRun || !panels.size) return;
      await pause(wait);
      wait = Math.min(MAX_RETRY_MS, wait * 2);
    }
  } finally {
    if (run === streamRun) pumping = false;
  }
}

/** Nothing left listening: let the stream go rather than hold a request open
 *  against an app nobody is watching. */
function stopEvents() {
  streamRun += 1;
  pumping = false;
  try {
    streamAbort?.abort();
  } catch {
    /* already gone */
  }
  streamAbort = null;
}

api.runtime.onConnect.addListener((port) => {
  if (port.name !== SYNC_PORT) return;
  panels.add(port);
  // The panel says so every so often (`mapoverlay.js`). Two things ride on it:
  // this worker is kept from being evicted mid-sweep, and a stream that died
  // with an eviction is opened again without anyone touching the panel.
  port.onMessage.addListener(() => pumpEvents());
  port.onDisconnect.addListener(() => {
    panels.delete(port);
    if (!panels.size) stopEvents();
  });
  pumpEvents();
});

// --- linked views --------------------------------------------------------------
//
// The app's Link button puts two of its map tabs on one camera over a
// BroadcastChannel (`frontend/src/lib/map/link.js`). A panel on a site's map
// cannot join that channel — it is another origin — so the worker is the hub for
// everything the channel cannot reach: panel to panel, and panel to app, whose
// bridge opens a port here for each map tab (`bridge.js`).
//
// A panel follows a view by writing it into its own address bar
// (`maplink.js`), and most sites reload for that. A reload takes the panel with
// it, so two facts have to outlive the page and live here: which tabs are linked,
// and which one is on its way to a view it was sent. The second is what puts the
// tools back once the page has loaded (`resumeFollow`), and what keeps a tab
// counted as a peer while it reloads: without it the tab leading would see its
// only peer vanish mid-follow and switch its own link off.
//
// Nothing here is written down beyond the session, and nothing reaches the
// network: a camera is not case state.

const LINK_PORT = "map-link";
/** How long a tab that left to follow a view is waited for. Earth takes a
 *  dozen seconds to load on a machine without a GPU. */
const FOLLOW_GRACE_MS = 30000;

/** Every port on the link: `{ tabId, app }`, where `app` is one of the app's
 *  own map tabs rather than a panel. */
const linkPorts = new Map();
/** `{ linked: tabId[], following: { [tabId]: { at, view, pending } } }`,
 *  mirrored to storage.session because the worker may be evicted between two
 *  gestures. `pending` is a camera sent while that tab was away reloading. */
let linkMemo = null;
/** Tabs whose tools are being put back, so a page that reports "complete" twice
 *  is not injected twice — a second injection closes the panel. */
const resuming = new Set();

async function linkMemory() {
  if (!linkMemo) {
    const stored = (await api.storage.session.get({ mapLink: null }))?.mapLink;
    linkMemo = { linked: stored?.linked ?? [], following: stored?.following ?? {} };
  }
  return linkMemo;
}

function rememberLinks() {
  api.storage.session.set({ mapLink: linkMemo });
}

/** Tabs still waited for, the stale ones dropped on the way. */
function waitedFor(memo) {
  const now = Date.now();
  for (const [tabId, follow] of Object.entries(memo.following)) {
    if (now - follow.at >= FOLLOW_GRACE_MS) delete memo.following[tabId];
  }
  return memo.following;
}

/** Only the four numbers of a camera cross the hub, and only real ones. */
function linkView(view) {
  const ok =
    view &&
    Number.isFinite(view.lat) &&
    Number.isFinite(view.lon) &&
    Number.isFinite(view.zoom) &&
    Math.abs(view.lat) <= 90 &&
    Math.abs(view.lon) <= 180;
  if (!ok) return null;
  return { lat: view.lat, lon: view.lon, zoom: view.zoom, bearing: Number.isFinite(view.bearing) ? view.bearing : 0 };
}

function linkPost(port, message) {
  try {
    port.postMessage(message);
  } catch {
    // the tab went while this was in hand; its disconnect is already queued
  }
}

/**
 * Tell every port how many others it could link to.
 *
 * A panel counts everything else on the link. An app tab counts only panels,
 * because it already counts the app's other tabs on its own channel. A tab
 * reloading on its way to a view counts for both, for as long as it is waited
 * for.
 */
function linkPeers() {
  const panels = [...linkPorts.values()].filter((who) => !who.app);
  const present = new Set(panels.map((who) => who.tabId));
  const returning = linkMemo
    ? Object.keys(waitedFor(linkMemo)).filter((tabId) => !present.has(Number(tabId))).length
    : 0;
  for (const [port, who] of linkPorts) {
    const count = who.app ? panels.length + returning : linkPorts.size - 1 + returning;
    linkPost(port, { type: "link-peers", count });
  }
}

/**
 * Keep a camera for every linked tab that is away reloading.
 *
 * A panel that left to follow one view is not connected while its page loads,
 * and the analyst does not wait for it: the map being led goes on moving. Each
 * of those cameras used to be dropped, and the tab landed on the first and stayed
 * there. Only the last one matters, and the tab is handed it when it is back.
 */
function holdForReturning(memo, view, fromTabId) {
  const present = new Set([...linkPorts.values()].filter((who) => !who.app).map((who) => who.tabId));
  let held = false;
  for (const [tabId, follow] of Object.entries(waitedFor(memo))) {
    const id = Number(tabId);
    if (id === fromTabId || present.has(id) || !memo.linked.includes(id)) continue;
    follow.pending = view;
    held = true;
  }
  if (held) rememberLinks();
}

async function onLinkMessage(port, msg) {
  const who = linkPorts.get(port);
  if (!who || !msg) return;
  const memo = await linkMemory();
  if (who.app) {
    // An app tab only ever speaks a camera, and only to the panels: the app's
    // other tabs heard it on their own channel.
    const view = msg.type === "view" ? linkView(msg.view) : null;
    if (!view) return;
    for (const [other, them] of linkPorts) {
      if (!them.app && memo.linked.includes(them.tabId)) linkPost(other, { type: "view", view });
    }
    holdForReturning(memo, view, null);
    return;
  }
  if (msg.type === "link") {
    memo.linked = memo.linked.filter((id) => id !== who.tabId);
    if (msg.on) memo.linked.push(who.tabId);
    else delete memo.following[who.tabId];
    rememberLinks();
    linkPost(port, { type: "link-state", linked: !!msg.on, asked: null });
    return;
  }
  if (msg.type === "follow") {
    memo.following[who.tabId] = { at: Date.now(), view: linkView(msg.view) };
    rememberLinks();
    // the count drops back once the wait is over, whether or not the tab came
    setTimeout(linkPeers, FOLLOW_GRACE_MS + 50);
    return;
  }
  if (msg.type === "landed") {
    // a hash the site took without reloading: the panel never left
    delete memo.following[who.tabId];
    rememberLinks();
    return;
  }
  if (msg.type === "view") {
    const view = linkView(msg.view);
    if (!view || !memo.linked.includes(who.tabId)) return;
    for (const [other, them] of linkPorts) {
      if (other === port) continue;
      if (them.app || memo.linked.includes(them.tabId)) linkPost(other, { type: "view", view });
    }
    holdForReturning(memo, view, who.tabId);
  }
}

async function openLink(port) {
  const tab = port.sender?.tab;
  if (!tab?.id && tab?.id !== 0) {
    port.disconnect();
    return;
  }
  const who = { tabId: tab.id, app: isAppUrl(tab.url) };
  linkPorts.set(port, who);
  // before anything is awaited, so nothing the port says first is missed
  port.onMessage.addListener((msg) => onLinkMessage(port, msg));
  port.onDisconnect.addListener(() => {
    linkPorts.delete(port);
    linkPeers();
  });
  const memo = await linkMemory();
  if (!who.app) {
    // A panel arriving where it was sent: it hears that it is linked, the view
    // it was sent to (so it can say how close this map came), and whatever the
    // map it follows did while it was loading. The wait itself stands until it
    // runs out: a site may load a second document, and the tools go back on that
    // one too.
    const follow = waitedFor(memo)[tab.id];
    const linked = memo.linked.includes(tab.id);
    linkPost(port, { type: "link-state", linked, asked: follow?.view ?? null });
    if (follow?.pending && linked) {
      linkPost(port, { type: "view", view: follow.pending });
      delete follow.pending;
      rememberLinks();
    }
  }
  linkPeers();
}

api.runtime.onConnect.addListener((port) => {
  if (port.name === LINK_PORT) openLink(port);
});

/**
 * Put the tools back on a tab that reloaded to follow a view.
 *
 * Only a tab that said it was leaving for one, and only while it is waited for:
 * a linked tab the analyst reloads, or navigates somewhere else, loses its panel
 * the way any tab does. The panel is looked for first because a site that takes
 * the view in its hash reports "complete" without ever unloading it, and
 * injecting an open panel again is what closes it.
 *
 * A browser may refuse, and that is the one real cost of following by address:
 * where the extension holds no host permission, the tools were only ever allowed
 * on the page that was open when the button was pressed. The other linked panels
 * say so rather than leaving a tab that silently stopped following.
 */
/** How often, and how far apart, a refused injection is tried again. A page
 *  that reports "complete" can still be swapping its document, and the first
 *  refusal is often only that. */
const RESUME_TRIES = 3;
const RESUME_RETRY_MS = 1000;

async function resumeFollow(tabId, attempt = 1) {
  const memo = await linkMemory();
  const follow = waitedFor(memo)[tabId];
  if (!follow || resuming.has(tabId)) return;
  resuming.add(tabId);
  try {
    const [probe] = await api.scripting.executeScript({
      target: { tabId },
      func: () => Boolean(window.__AZIMUT_MAP_TOOLS__),
    });
    if (!probe?.result) await api.scripting.executeScript({ target: { tabId }, files: MAP_FILES });
  } catch {
    if (attempt < RESUME_TRIES) {
      setTimeout(() => resumeFollow(tabId, attempt + 1), RESUME_RETRY_MS);
      return;
    }
    delete memo.following[tabId];
    memo.linked = memo.linked.filter((id) => id !== tabId);
    rememberLinks();
    for (const [port, who] of linkPorts) {
      if (!who.app) {
        linkPost(port, { type: "link-note", note: "A linked tab reloaded and the browser kept its tools off. Open them there again" });
      }
    }
    linkPeers();
  } finally {
    resuming.delete(tabId);
  }
}

api.tabs.onUpdated.addListener((tabId, info) => {
  if (info?.status === "complete") resumeFollow(tabId);
});

api.tabs.onRemoved?.addListener(async (tabId) => {
  const memo = await linkMemory();
  if (!memo.linked.includes(tabId) && !memo.following[tabId]) return;
  memo.linked = memo.linked.filter((id) => id !== tabId);
  delete memo.following[tabId];
  rememberLinks();
});

// --- message routes ------------------------------------------------------------

async function handle(msg, sender) {
  // The Azimut app's own Capture button (bridge.js relay): return the raw
  // frame — the app does its own registration, cropping and filing. Only the
  // app's localhost origin may ask for it.
  if (msg.type === "capture-tab") {
    const refused = await notTheApp(sender.tab);
    if (refused) return { ok: false, error: refused };
    try {
      const dataUrl = await withoutPanel(sender.tab.id, () => captureActiveTab(sender.tab.windowId));
      return { ok: true, dataUrl };
    } catch (e) {
      // captureVisibleTab needs activeTab (or <all_urls>, which this extension
      // deliberately never asks for) — a page-initiated capture is refused
      // until the user has invoked the extension once on this tab. Tell the
      // app which case this is, so it can explain the one-time step.
      const needsActivation = /activeTab|all_urls|permission/i.test(e.message || "");
      return { ok: false, needsActivation, error: e.message };
    }
  }

  // Popup: arm an area selection on the page. The popup closes right after,
  // so the meta waits in storage.session for the overlay's rect.
  if (msg.type === "start-area-select") {
    try {
      await api.storage.session.set({ [`pending:${msg.tabId}`]: msg.meta });
      await api.scripting.executeScript({ target: { tabId: msg.tabId }, files: ["overlay.js"] });
      return { ok: true };
    } catch (e) {
      return { ok: false, error: e.message };
    }
  }

  // Overlay: the user finished (or cancelled) the drag.
  if (msg.type === "area-selected" || msg.type === "area-cancelled") {
    const key = `pending:${sender.tab.id}`;
    const meta = (await api.storage.session.get(key))[key];
    await api.storage.session.remove(key);
    if (msg.type === "area-cancelled" || !meta) return { ok: true };
    try {
      const dataUrl = await withoutPanel(sender.tab.id, () => captureActiveTab(sender.tab.windowId));
      const { blob, scale } = await cropDataUrl(dataUrl, msg.rect, msg.viewportW);
      const body = await ingest(blob, { ...meta, deviceScale: scale });
      notify("Capture filed into Azimut", body.title);
      return { ok: true };
    } catch (e) {
      notify("Azimut capture failed", e.message);
      return { ok: false, error: e.message };
    }
  }

  // The app's Publish button, relayed by bridge.js: open the composer and fill
  // the thread. Same origin check as the capture route — only the app may ask.
  if (msg.type === "post-handoff") {
    const refused = await notTheApp(sender.tab);
    if (refused) return { ok: false, error: refused };
    try {
      return await handOff(msg.payload ?? {});
    } catch (e) {
      return { ok: false, error: e.message };
    }
  }

  // The app's Reverse Search buttons, relayed by bridge.js: open the engine and
  // give it the image. Same origin check as every other app route.
  if (msg.type === "reverse-handoff") {
    const refused = await notTheApp(sender.tab);
    if (refused) return { ok: false, error: refused };
    try {
      return await handOffReverse(msg.payload ?? {});
    } catch (e) {
      return { ok: false, error: e.message };
    }
  }

  // Popup: draw the map tools over this tab. Injecting the panel a second time
  // closes it, which is what makes one button both open and close.
  if (msg.type === "map-tools") {
    try {
      await api.scripting.executeScript({ target: { tabId: msg.tabId }, files: MAP_FILES });
      return { ok: true };
    } catch (e) {
      return { ok: false, error: e.message };
    }
  }

  // The panel, asking the app something. Content scripts cannot call it
  // themselves; see the relay above.
  if (msg.type === "map-api") {
    try {
      return { ok: true, data: await mapApi(msg) };
    } catch (e) {
      return { ok: false, error: e.message };
    }
  }

  // The panel, asking for a picture to lay over the map.
  if (msg.type === "map-image") {
    try {
      return { ok: true, src: await mapImage(msg) };
    } catch (e) {
      return { ok: false, error: e.message };
    }
  }

  // The panel, asking for a slice of one of the case's files — bytes rather than
  // JSON, and one chunk per message so a long video is not one huge string.
  if (msg.type === "map-file") {
    try {
      return { ok: true, file: await mapFile(msg.caseId, msg.path, msg.offset) };
    } catch (e) {
      return { ok: false, error: e.message };
    }
  }

  // Settings asking what this copy is: the version the browser parsed, the folder
  // stamp this code was loaded from, and whether the asking tab is the address this
  // copy is paired with. Identification only, so any loopback page may ask: an app
  // that moved to a free port must still find its extension, and be told why it
  // refuses to act for it.
  if (msg.type === "ext-state") {
    if (!sender.tab || !isAppUrl(sender.tab.url)) return { ok: false, error: "not the Azimut app" };
    return {
      ok: true,
      paired: await isPairedApp(sender.tab.url),
      version: api.runtime.getManifest().version,
      // Not `id`: the bridge spreads this answer next to the message's own
      // correlation id, and a collision there would break the pairing silently.
      extensionId: api.runtime.id,
      loaded: await loadedStamp(),
      installType: await installType(),
    };
  }

  // Settings' Update button, after the app has rewritten the folder: restart so
  // the browser re-reads it.
  //
  // Answering *before* reloading is not a nicety. reload() kills this worker at
  // once, so a handler that reloads first never replies and the app is left
  // holding a rejected port. And the reply is only "taken", never "worked": what
  // proves the code moved is the stamp read back afterwards.
  if (msg.type === "ext-reload") {
    const refused = await notTheApp(sender.tab);
    if (refused) return { ok: false, error: refused };
    const stamp = await loadedStamp();
    // Two copies of this extension can be loaded at once on Chrome, which
    // derives the extension id from the folder path (see the app's Settings
    // copy). The message names the install the app means; the other copy must
    // keep its hands down, because restarting the wrong one is silent and looks
    // exactly like a failed update.
    if (msg.installId && msg.installId !== stamp?.install_id) {
      return { ok: false, error: "another copy of the extension" };
    }
    setTimeout(() => api.runtime.reload(), 50);
    return { ok: true, reloading: true };
  }

  return { ok: false, error: `unknown message '${msg.type}'` };
}

api.runtime.onMessage.addListener((msg, sender, sendResponse) => {
  handle(msg, sender).then(sendResponse, (e) => sendResponse({ ok: false, error: e.message }));
  return true; // async response
});

// Worker start — including the one right after ext-reload, which is the point.
reattachBridge();