The OSINT investigator's workbench. One case, one folder, every tool. Local-first: your media and your investigations never leave your machine.
JavaScript
/**
* App side of the capture-extension bridge (extension/bridge.js).
*
* The Google (Maps JS) widget basemap has no tiles to stitch and its DOM
* imagery is off-limits (IMAGERY_PROVIDERS.md), so its Capture button needs
* screen pixels. The extension supplies them through one tabs.captureVisibleTab
* behind the user's click — no share prompt, no sharing bar, fullscreen kept —
* and this module is the only place the app talks to it.
*
* Detection is synchronous: the extension's content script stamps
* `data-azimut-capture-extension` on <html> at document_start, before the app
* mounts. Installing the extension with the app already open therefore needs
* one tab reload — Settings says so next to the install button.
*/
const CHANNEL = 'azimut-capture-ext';
/** The installed extension's version, or null. */
export function extensionVersion(doc = document) {
return doc.documentElement.dataset.azimutCaptureExtension || null;
}
/**
* Is `bundled` a newer extension than `installed`? Numeric per-part compare, so
* 0.1.10 beats 0.1.9 and a `v` prefix or pre-release suffix doesn't fool it.
* False when either side is missing — nothing to update to, or nothing to
* update. Mirrors the app-side check in engine/updates.py.
*/
export function extensionOutdated(installed, bundled) {
if (!installed || !bundled) return false;
const parse = (v) => String(v).replace(/^v/i, '').split('.').map((n) => parseInt(n, 10) || 0);
const [a, b] = [parse(bundled), parse(installed)];
for (let i = 0; i < Math.max(a.length, b.length); i++) {
if ((a[i] || 0) !== (b[i] || 0)) return (a[i] || 0) > (b[i] || 0);
}
return false;
}
let seq = 0;
/**
* One frame of this tab (a PNG data URL), via the extension.
* Rejects when the extension is absent, silent (timeout) or refused by the
* browser — the caller owns the user-facing explanation.
*/
export function captureTab({ timeoutMs = 4000, win = window } = {}) {
return new Promise((resolve, reject) => {
const id = `cap-${++seq}`;
const timer = setTimeout(() => {
win.removeEventListener('message', onMessage);
reject(new Error('the capture extension did not answer'));
}, timeoutMs);
function onMessage(event) {
// origin is the boundary that matters: the reply must come from our own
// page (where only our bridge content script posts on this channel).
// No event.source check — the app hosts no same-origin iframes, and
// happy-dom (tests) never sets source to the window like browsers do.
if (event.origin !== win.location.origin) return;
const msg = event.data;
if (!msg || msg.channel !== CHANNEL || msg.type !== 'capture-result' || msg.id !== id) return;
clearTimeout(timer);
win.removeEventListener('message', onMessage);
if (msg.ok && msg.dataUrl) {
resolve(msg.dataUrl);
} else {
const err = new Error(msg.error || 'the capture extension refused');
// browsers refuse tab screenshots until the extension has been invoked
// once on the tab (activeTab) — a distinct, one-time, fixable case
err.needsActivation = !!msg.needsActivation;
reject(err);
}
}
win.addEventListener('message', onMessage);
win.postMessage({ channel: CHANNEL, type: 'capture', id }, win.location.origin);
});
}
/**
* Hand a prepared thread to the extension, which opens the composer and fills it.
*
* Resolves when the extension **takes** it, not when it has finished: filling is
* tens of seconds — a tab, a composer mounting, a file at a time — and the answer
* needed here is only whether the app should stand down. What the fill managed is
* reported by the extension's own notifications.
*
* A rejection is not a failure to report: it means the app still owns the
* hand-off and opens the intent page itself, exactly as it does with no extension
* installed. Absent, switched off, not permitted on that site, silent: one
* answer, one fallback.
*
* Hence the short timeout. It is a question with three cheap checks behind it,
* and the caller is holding a click — a browser only lets a page open a tab for a
* few seconds after one, so a slow no would spend the click and open nothing. An
* old extension that has never heard of this message answers by staying silent,
* which is exactly the case the timeout is short for.
*
* Nothing but paths crosses this channel. The extension fetches the bytes from
* the local app with its own pairing token, so no case file is ever posted into
* the page, and the token never reaches the app's DOM.
*/
export function handOffPost(payload, { timeoutMs = 2000, win = window } = {}) {
return new Promise((resolve, reject) => {
const id = `post-${++seq}`;
const timer = setTimeout(() => {
win.removeEventListener('message', onMessage);
reject(new Error('the capture extension did not answer'));
}, timeoutMs);
function onMessage(event) {
if (event.origin !== win.location.origin) return;
const msg = event.data;
if (!msg || msg.channel !== CHANNEL || msg.type !== 'post-handoff-result' || msg.id !== id) return;
clearTimeout(timer);
win.removeEventListener('message', onMessage);
if (msg.ok) resolve(true);
else reject(new Error(msg.error || 'the capture extension refused'));
}
win.addEventListener('message', onMessage);
win.postMessage({ channel: CHANNEL, type: 'post-handoff', id, payload }, win.location.origin);
});
}
/**
* Hand a prepared image to the extension, which opens the engine and gives it
* the picture.
*
* Same contract as the thread above, and the same reason for the short timeout:
* the app is holding a click, and a slow no would spend it and open nothing.
* Resolving means the extension **took** it, never that the engine liked it — it
* has not opened the tab yet. A rejection means the app still owns the hand-off
* and does what it always did: open the page, with the image on the clipboard or
* saved to disk.
*
* Unlike the thread, the bytes go through here. What Reverse Search prepares is
* a frame off a canvas — a video still, adjustments baked in — so there is no
* path for the extension to read it back from.
*/
export function handOffReverse(payload, { timeoutMs = 2000, win = window } = {}) {
return new Promise((resolve, reject) => {
const id = `rev-${++seq}`;
const timer = setTimeout(() => {
win.removeEventListener('message', onMessage);
reject(new Error('the capture extension did not answer'));
}, timeoutMs);
function onMessage(event) {
if (event.origin !== win.location.origin) return;
const msg = event.data;
if (!msg || msg.channel !== CHANNEL || msg.type !== 'reverse-handoff-result' || msg.id !== id) return;
clearTimeout(timer);
win.removeEventListener('message', onMessage);
if (msg.ok) resolve(true);
else reject(new Error(msg.error || 'the capture extension refused'));
}
win.addEventListener('message', onMessage);
win.postMessage({ channel: CHANNEL, type: 'reverse-handoff', id, payload }, win.location.origin);
});
}
/**
* Subscribe to the extension's "activated" signal: the user just clicked the
* extension on this tab (granting activeTab), so a previously refused capture
* can now be retried. Returns an unsubscribe function.
*/
export function onActivated(cb, win = window) {
const onMessage = (event) => {
if (event.origin !== win.location.origin) return;
const msg = event.data;
if (msg && msg.channel === CHANNEL && msg.type === 'activated') cb();
};
win.addEventListener('message', onMessage);
return () => win.removeEventListener('message', onMessage);
}
/**
* Subscribe to a bridge announcing itself: the manifest injected it at
* document_start, or the background re-injected it after an update. Either way
* the version it carries is the one now running. Returns an unsubscribe function.
*/
export function onBridgeHello(cb, win = window) {
const onMessage = (event) => {
if (event.origin !== win.location.origin) return;
const msg = event.data;
if (msg && msg.channel === CHANNEL && msg.type === 'bridge-hello') cb(msg.version || null);
};
win.addEventListener('message', onMessage);
return () => win.removeEventListener('message', onMessage);
}
/**
* This map tab's end of the extension's linked views, or null without one.
*
* The extension's map tools panel follows a camera on sites outside the app, and
* its worker is the hub between those panels and the app's map tabs
* (`background.js`, "linked views"). The bridge holds this tab's port to it;
* this is the app side of that, in the shape `map/link.js` takes as a `relay`.
*
* Two message types rather than one, because the page hears its own
* postMessage: `map-link` goes to the bridge and `map-link-event` comes back,
* so a camera this tab sends is never mistaken for one it was handed.
*
* Nothing leaves the machine. The bridge relays to the extension's worker, which
* relays to panels in other tabs of the same browser.
*/
export function mapLinkRelay({ win = window, doc = document } = {}) {
if (!extensionVersion(doc)) return null;
let heard = null;
const post = (kind, extra) =>
win.postMessage({ channel: CHANNEL, type: 'map-link', kind, ...extra }, win.location.origin);
function onMessage(event) {
if (event.origin !== win.location.origin || !heard) return;
const msg = event.data;
if (!msg || msg.channel !== CHANNEL) return;
// an extension that restarted brought a bridge with no port: ask again
if (msg.type === 'bridge-hello') return post('open');
if (msg.type !== 'map-link-event') return;
if (msg.kind === 'view') heard.view(msg.view);
if (msg.kind === 'peers') heard.peers(msg.count);
}
return {
listen(handlers) {
heard = handlers;
win.addEventListener('message', onMessage);
post('open');
},
send(view) {
post('view', { view });
},
close() {
post('close');
win.removeEventListener('message', onMessage);
heard = null;
},
};
}
/**
* Every live bridge on this tab, as `[{version}]`.
*
* `ping` is the one message every version of the extension has ever answered,
* which is exactly why detection hangs off it rather than off `ext-state`: a
* copy installed before the update button existed cannot answer the newer
* message, and asking only that would report an extension the analyst is plainly
* running as "not detected".
*
* Counting is the other half of its job. Two copies can be loaded at once (see
* `extensionState`), and a copy too old to identify itself still answers here —
* so the number of pongs is the honest answer to "how many extensions are on
* this channel", where the number of `ext-state` replies is only "how many can
* the app manage".
*
* Never rejects: silence means nothing is installed, which is an answer.
*/
export function pingExtensions({ timeoutMs = 700, win = window } = {}) {
return new Promise((resolve) => {
const id = `ping-${++seq}`;
const found = [];
function onMessage(event) {
if (event.origin !== win.location.origin) return;
const msg = event.data;
if (!msg || msg.channel !== CHANNEL || msg.type !== 'pong' || msg.id !== id) return;
found.push({ version: msg.version || null });
}
win.addEventListener('message', onMessage);
setTimeout(() => {
win.removeEventListener('message', onMessage);
resolve(found);
}, timeoutMs);
win.postMessage({ channel: CHANNEL, type: 'ping', id }, win.location.origin);
});
}
/**
* Every copy of the extension loaded on this tab that can identify itself, each
* with the version the browser parsed, its extension id, and the install stamp
* the *running* code was loaded from (`engine/extinstall.py` writes it; null
* means a folder the app doesn't own).
*
* A copy older than this message answers nothing here. That is not "absent" —
* `pingExtensions` is what says whether anything is loaded at all.
*
* Collects for the whole window instead of resolving on the first answer, which
* is the one thing this cannot do. Chrome derives the extension id from the
* folder path, so someone who loads the app-owned copy without removing their old
* unzip is running two extensions: same name, same channel, same message id, two
* replies. Resolving on the first would report a coin toss, and the caller needs
* to know there are two so it can say which to remove.
*
* Resolves to `[]` when nothing answers — not installed, or too old to know this
* message. Never rejects: "no extension" is an answer, not a failure.
*/
export function extensionState({ timeoutMs = 700, win = window } = {}) {
return new Promise((resolve) => {
const id = `state-${++seq}`;
const found = [];
function onMessage(event) {
if (event.origin !== win.location.origin) return;
const msg = event.data;
if (!msg || msg.channel !== CHANNEL || msg.type !== 'ext-state-result' || msg.id !== id) return;
if (msg.ok) {
found.push({
version: msg.version || null,
extensionId: msg.extensionId || null,
loaded: msg.loaded ?? null,
// "development" for a folder or a temporary add-on, "normal" for a
// packaged copy the browser manages. Null from a copy predating it.
installType: msg.installType ?? null,
// False when this tab is not the address the copy is paired with: it then
// refuses to capture or hand off for it. Null from a copy predating it.
paired: msg.paired ?? null,
});
}
}
win.addEventListener('message', onMessage);
setTimeout(() => {
win.removeEventListener('message', onMessage);
resolve(found);
}, timeoutMs);
win.postMessage({ channel: CHANNEL, type: 'ext-state', id }, win.location.origin);
});
}
/**
* Ask the copy installed at `installId` to restart, so the browser re-reads the
* folder the app just rewrote.
*
* The `installId` is not decoration: with two copies loaded, an unaddressed
* reload restarts whichever answers first, which is silent and looks exactly
* like an update that didn't take. A copy that isn't the one named ignores it.
*
* Resolving means the message was *taken*, never that the new code is running —
* the extension dies mid-reply by design. What proves the update landed is
* reading the stamp back afterwards, so a timeout here is inconclusive rather
* than fatal and the caller verifies either way.
*/
export function reloadExtension(installId, { timeoutMs = 2000, win = window } = {}) {
return new Promise((resolve, reject) => {
const id = `reload-${++seq}`;
const timer = setTimeout(() => {
win.removeEventListener('message', onMessage);
reject(new Error('the capture extension did not answer'));
}, timeoutMs);
function onMessage(event) {
if (event.origin !== win.location.origin) return;
const msg = event.data;
if (!msg || msg.channel !== CHANNEL || msg.type !== 'ext-reload-result' || msg.id !== id) return;
clearTimeout(timer);
win.removeEventListener('message', onMessage);
if (msg.ok) resolve(true);
else reject(new Error(msg.error || 'the capture extension refused'));
}
win.addEventListener('message', onMessage);
win.postMessage({ channel: CHANNEL, type: 'ext-reload', id, installId }, win.location.origin);
});
}