Open-source AI coworkers that each get a computer of their own: a browser, files and tools, with every action decided before it happens and recorded after. Bring any AG-UI agent.
import {
type ExchangeResponse,
type RecorderMe,
recorderPaths,
} from "@openbot/shared/recorder-api";
import {
RECORDER_CONNECT_STATUS,
type TrustedConnectRule,
} from "@openbot/shared/recorder-page";
import type {
ExternalResponse,
ExternalToBackground,
PageResponse,
PageToBackground,
} from "../protocol/messages";
import { defaultBrowserName } from "../shared/browser-name";
import { OpenBotError, openbotJson } from "../shared/openbot-client";
import { normaliseOpenBotOrigin } from "../shared/origin";
import {
allowsOpenBot,
onPolicyChanged,
type RecorderPolicy,
readPolicy,
} from "../shared/policy";
import {
type ConnectionRecord,
installIdFor,
installSecret,
type PendingConnect,
readLocal,
readSession,
removeLocal,
removeSession,
writeLocal,
writeSession,
} from "../shared/storage";
import type { DesktopHandoff, DesktopRefusal } from "./native-host";
import {
askDesktopForHandoff,
desktopAddress,
desktopAvailable,
} from "./native-host";
/** A connection that ended without the person's Disconnect, for the recording controller (index.ts wires it in): OpenBot
* answered the keep-alive signed out (nothing is forgotten yet), the organization's policy moved the Recorder away from
* the connection's OpenBot (it is forgotten already), or a connection to another OpenBot, or for another person,
* replaced it (`endReplaced`: it is replaced already, and its token is revoked once the controller has stopped using
* it). */
export type ConnectionLoss =
| {
kind: "signed-out";
reason: "revoked" | "removed" | "organization";
connection: ConnectionRecord;
}
| { kind: "policy"; connection: ConnectionRecord }
| { kind: "replaced"; connection: ConnectionRecord };
type ConnectionDeps = {
askDesktop: () => Promise<DesktopHandoff | DesktopRefusal | null>;
desktopAvailable: () => Promise<boolean>;
/** OpenBot Desktop's own OpenBot address, as its native host confirms it (native-host.ts `desktopAddress`). */
desktopAddress: () => Promise<string | null>;
readPolicy: () => Promise<RecorderPolicy>;
openTab: (url: string) => Promise<number | undefined>; // the new tab's id, kept in pendingConnect.tabId
/** Stops what the lost connection still has running: the live recording and whatever the document sends with its
* token. Without the recording controller (a test of this module alone), a sign-out only forgets the connection. */
connectionLost: (loss: ConnectionLoss) => Promise<void>;
/** What an approved Connect does next, for the connection OpenBot Desktop made at install (index.ts wires in the
* recording controller's): a recording of this person goes on under the new token, and their kept recordings are
* sent. The popup's own Desktop connect reaches it through the router, as an approved Connect does. */
connected: () => Promise<void>;
};
const PENDING_MAX_AGE_MS = 5 * 60 * 1000;
const OUT_OF_DATE =
"This page is out of date. Close it and choose Connect this browser in OpenBot again.";
const POLICY_REFUSED =
"Your organization's Recorder policy does not allow this OpenBot. Ask your IT team.";
/**
* What the Connect page says when OpenBot did not take the code, by what OpenBot answered. Always the Recorder's own
* sentence and never the text in OpenBot's answer: the site that asked to connect is any site at all until the person
* approves it, and the Connect page is the Recorder's own, so a sentence from that site's server would speak in the
* Recorder's voice (telling the person to install something, say).
*/
const EXCHANGE_REFUSED: Record<number, string> = {
400: "This connect request has expired or was already used. Choose Connect this browser in OpenBot again.",
403: "This OpenBot does not accept this copy of the Recorder. Ask whoever runs it to add it.",
429: "OpenBot is taking too many connect requests just now. Try again in a few minutes.",
};
const EXCHANGE_FAILED = "OpenBot could not connect this browser. Try again.";
const UNREACHABLE = "OpenBot did not answer. Try again.";
/** Nothing about this copy: any site can ask to connect, and until the person approves it on the Connect page that site
* is any site. Its version and its install id for that origin go to it once it is connected (`ping`). */
const AWAITING_CONFIRMATION: ExternalResponse = {
ok: true,
awaitingConfirmation: true,
};
/** Web connects one OpenBot origin may ask for in any ten minutes: enough that an ordinary run (connect, connect again,
* again after a Disconnect or a revoke, a retry or two) never meets it, while a page asking over and over is held off. */
const CONNECT_WINDOW_MS = 10 * 60 * 1000;
const CONNECT_LIMIT = 10;
const KEEP_ALIVE_ALARM = "recorder-session-keepalive";
const KEEP_ALIVE_PERIOD_MINUTES = 720;
const KEEP_ALIVE_PERIOD_MS = KEEP_ALIVE_PERIOD_MINUTES * 60 * 1000;
/** How long OpenBot Desktop's code waits on its exchange. It runs in the connect queue (see `serially`), so a local OpenBot
* that never answers must not hold every connect behind it. A trusted OpenBot's page waits as long for its own. */
const DESKTOP_EXCHANGE_WAIT_MS = 10_000;
const defaultDeps: ConnectionDeps = {
askDesktop: askDesktopForHandoff,
desktopAvailable,
desktopAddress,
readPolicy,
openTab: async (url) => (await chrome.tabs.create({ url })).id,
connectionLost: async (loss) => {
if (loss.kind === "signed-out")
await forgetConnection(loss.reason, loss.connection.token);
},
connected: async () => {},
};
const withDefaults = (deps?: Partial<ConnectionDeps>): ConnectionDeps => ({
...defaultDeps,
...deps,
});
const connectUrl = () => chrome.runtime.getURL("connect.html");
/** A web connect, Desktop's connect and a decision's clear (`clearPendingConnect`) each read, then write, the pending
* connect (and a web connect the request count) across storage awaits, so they run one at a time: run side by side,
* ten connects in one tick would each find the slot empty and open a tab, and the limit would count one of them. A
* forget told which token asked (`forgetConnection` with `askedWith`), approve's store of the connection and the
* launcher's queue here too. A job that throws rejects its own caller and the next job still runs. */
let queue: Promise<unknown> = Promise.resolve();
/** Launcher connections waiting in the queue: an install's own Desktop connect, ahead of one there, stores nothing. */
let launcherConnecting = 0;
function serially<T>(work: () => Promise<T>): Promise<T> {
const run = queue.then(work, work);
queue = run.catch(() => undefined);
return run;
}
export function installConnection(deps?: Partial<ConnectionDeps>): void {
const resolved = withDefaults(deps);
chrome.runtime.onInstalled.addListener(async (details) => {
if (details.reason !== "install") return;
await installSecret();
// A Recorder OpenBot Desktop put in this browser connects as it installs, with nothing to click.
const answer = await connectThroughDesktop(resolved, { install: true });
if (answer.connected)
await resolved
.connected()
.catch((error) =>
console.error("Recorder: reconnect follow-up failed", error),
);
});
chrome.alarms.onAlarm.addListener((alarm) => {
if (alarm.name === KEEP_ALIVE_ALARM) void keepAlive(resolved);
});
void reconcilePolicy(resolved);
onPolicyChanged(() => void reconcilePolicy(resolved), resolved.readPolicy);
void scheduleKeepAlive(resolved);
}
/** Alarms can be cleared by a browser restart or an update, so every start makes sure it exists. */
async function scheduleKeepAlive(deps: ConnectionDeps): Promise<void> {
if (!(await chrome.alarms.get(KEEP_ALIVE_ALARM)))
await chrome.alarms.create(KEEP_ALIVE_ALARM, {
periodInMinutes: KEEP_ALIVE_PERIOD_MINUTES,
});
const last = await readLocal("lastKeepAliveAt");
if (last === undefined || Date.now() - last > KEEP_ALIVE_PERIOD_MS)
await keepAlive(deps);
}
/** Keeps the organization session in use (Decision 2). Only a signed-out answer changes anything: OpenBot being
* unreachable, or an organization's sign-in server that cannot answer, waits for the next alarm. A signed-out answer
* goes to the recording controller, which forgets the connection and stops what it still has running. */
async function keepAlive(deps: ConnectionDeps): Promise<void> {
const connection = await currentConnection();
if (!connection) return;
try {
await openbotJson<RecorderMe>(connection, recorderPaths.me);
} catch (error) {
if (error instanceof OpenBotError && error.signedOut)
await deps.connectionLost({
kind: "signed-out",
reason: error.body?.reason ?? "revoked",
connection,
});
return;
}
await writeLocal("lastKeepAliveAt", Date.now());
}
export async function currentConnection(): Promise<ConnectionRecord | null> {
return (await readLocal("connection")) ?? null;
}
type ForgetReason = "revoked" | "removed" | "organization" | "disconnected";
/** Forgets the stored connection, with a signed-out notice giving the reason unless the person disconnected.
*
* A caller handling a failed request (a signed-out answer, or a Disconnect's DELETE) must pass the token that request
* used as `askedWith`. Reconnecting this copy revokes its old token, so a request sent with the old token can finish
* after approve stored the new connection: with `askedWith`, only the connection that asked is forgotten, notice and
* all. The check and the forget are one queued job, and approve stores through the queue, so no new connection lands
* between them. Without `askedWith`, whatever connection is stored is forgotten at once.
*
* Resolves true when it forgot a connection: false when `askedWith` is no longer the stored token, or when nothing was
* stored, so a caller can leave alone what belongs to a connection that stays. */
export async function forgetConnection(
reason: ForgetReason,
askedWith?: string,
): Promise<boolean> {
if (askedWith === undefined) {
const stored = await currentConnection();
await forget(reason);
return stored !== null;
}
return serially(async () => {
if ((await currentConnection())?.token !== askedWith) return false;
await forget(reason);
return true;
});
}
async function forget(reason: ForgetReason): Promise<void> {
await removeLocal("connection");
if (reason !== "disconnected")
await writeLocal("notice", { kind: "signed-out", at: Date.now(), reason });
}
/** page.connect.*, page.disconnect, page.desktop.available, page.connect.desktop; undefined for anything else. */
export async function handleConnectionMessage(
message: PageToBackground,
deps?: Partial<ConnectionDeps>,
): Promise<PageResponse | undefined> {
const resolved = withDefaults(deps);
switch (message.type) {
case "page.connect.pending": {
const pending = await readSession("pendingConnect");
// Approving replaces whatever this browser is connected to now, so the Connect page names it.
const connection = pending ? await currentConnection() : null;
return {
ok: true,
pending: pending ? { origin: pending.origin, via: pending.via } : null,
...(connection
? {
replaces: {
origin: connection.openbotUrl,
email: connection.user.email,
},
}
: {}),
};
}
case "page.connect.decide": {
const pending = await readSession("pendingConnect");
// A connect page reads the pending origin once, on load: a tab Chrome did not close when another origin
// replaced its pending connect (closeConnectTab) still shows the old one, and neither connects nor cancels the
// site it does not show.
if (pending && message.origin !== pending.origin)
return { ok: false, error: OUT_OF_DATE };
if (message.approve) return approve(pending, message.label, resolved);
if (pending) await clearPendingConnect(pending, { cancelled: true });
return { ok: true };
}
case "page.disconnect": {
const connection = await currentConnection();
if (connection) {
// Best effort: the token is forgotten here either way, and the person can revoke it in OpenBot.
await revoke(connection);
// A reconnect approved while OpenBot was being told is a newer connection, and stays.
await forgetConnection("disconnected", connection.token);
}
return { ok: true };
}
case "page.desktop.available":
return { ok: true, available: await resolved.desktopAvailable() };
case "page.connect.desktop":
return { ok: true, ...(await connectThroughDesktop(resolved)) };
default:
return undefined;
}
}
async function approve(
pending: PendingConnect | undefined,
label: string,
deps: ConnectionDeps,
): Promise<PageResponse> {
if (!pending) return { ok: false, error: "There is nothing to connect." };
// The policy may have changed since this connect page opened: a pin elsewhere, or a policy gone invalid, refuses it.
if (!allowsOpenBot(await deps.readPolicy(), pending.origin)) {
await clearPendingConnect(pending);
return { ok: false, error: POLICY_REFUSED };
}
let exchanged: ExchangeResponse;
try {
exchanged = await openbotJson<ExchangeResponse>(
{ openbotUrl: pending.origin },
recorderPaths.connections,
{
body: {
code: pending.code,
label,
installId: await installIdFor(pending.origin),
},
},
);
} catch (error) {
// The Recorder's own sentence for what OpenBot answered (EXCHANGE_REFUSED), or a plain one: a network failure's
// message ("Failed to fetch") means nothing here.
return {
ok: false,
error:
error instanceof OpenBotError
? (EXCHANGE_REFUSED[error.status] ?? EXCHANGE_FAILED)
: UNREACHABLE,
};
}
const connection: ConnectionRecord = {
openbotUrl: pending.origin,
token: exchanged.token,
connectionId: exchanged.connection.id,
user: exchanged.user,
via: pending.via,
connectedAt: Date.now(),
};
// Checked again in the job that stores it: a pin that landed during the exchange keeps it out, and the token OpenBot
// just made is revoked there. The connection it replaces is read in the same job.
const stored = await serially(async () => {
if (!allowsOpenBot(await deps.readPolicy(), pending.origin)) return null;
const replaced = await currentConnection();
await writeLocal("connection", connection);
return { replaced };
});
if (!stored) {
await clearPendingConnect(pending);
await revoke(connection);
return { ok: false, error: POLICY_REFUSED };
}
await endReplaced(stored.replaced, connection, deps);
await clearPendingConnect(pending);
if ((await readLocal("notice"))?.kind === "signed-out")
await removeLocal("notice");
return { ok: true };
}
/**
* What a connection that replaced another does about the one it replaced (`previous`, read in the queued job that stored
* `next`). The same person on the same OpenBot is this copy connecting again: OpenBot revoked the old token itself at the
* exchange (one live connection per person and install id), and a recording of theirs goes on under the new token
* (`connected`, then the recording controller's adoptConnection). Another person, or another OpenBot, lost their
* connection: the recording controller stops what still runs with its token and keeps everything for them, as a
* sign-out keeps it (`connectionLost`), then the old token is revoked at its own OpenBot, so no live token is left that
* this browser no longer holds. In that order, so nothing still sending with the old token meets its revocation first.
*/
async function endReplaced(
previous: ConnectionRecord | null,
next: ConnectionRecord,
deps: ConnectionDeps,
): Promise<void> {
if (!previous || previous.token === next.token) return;
if (
previous.openbotUrl === next.openbotUrl &&
previous.user.id === next.user.id
)
return;
await deps
.connectionLost({ kind: "replaced", connection: previous })
.catch((error) =>
console.error("Recorder: ending a replaced connection failed", error),
);
await revoke(previous);
}
/**
* The connection the Recorder's launcher hands it (launcher.ts), stored as an approved Connect stores one: checked
* against the policy in the same queued job that writes it, the signed-out notice gone with it. Nothing pending is
* asked about, so nothing is shown: the Recorder's own setup tab and a Connect page its install opened on its own are
* closed, since a browser OpenBot opened needs neither. Resolves false when the policy keeps it out.
*
* OpenBot Desktop's native host answers in an OpenBot browser's profile too, so on its first launch the install's own
* Desktop connect can land just before the launcher's connection. The one it replaces is revoked: this browser needs
* none, and OpenBot would otherwise go on counting it as a browser of the person's own that OpenBot Desktop connected.
*/
export async function connectFromLauncher(
connection: ConnectionRecord,
deps?: Partial<ConnectionDeps>,
): Promise<boolean> {
const resolved = withDefaults(deps);
launcherConnecting += 1;
let stored: { replaced: ConnectionRecord | null } | null;
try {
stored = await serially(async () => {
if (!allowsOpenBot(await resolved.readPolicy(), connection.openbotUrl))
return null;
const replaced = await currentConnection();
await writeLocal("connection", connection);
return { replaced };
});
} finally {
launcherConnecting -= 1;
}
if (!stored) return false;
const { replaced } = stored;
if (replaced?.via === "desktop" && replaced.token !== connection.token)
await revoke(replaced);
if ((await readLocal("notice"))?.kind === "signed-out")
await removeLocal("notice");
const setupTab = await readSession("setupTabId");
if (setupTab !== undefined) {
await closeConnectTab(setupTab);
await removeSession("setupTabId");
}
const pending = await readSession("pendingConnect");
if (pending?.via === "desktop") {
await closeConnectTab(pending.tabId);
await clearPendingConnect(pending);
}
return true;
}
/** A decision clears only the pending connect it read when it arrived. Approve's exchange runs outside the queue, so
* a connect never waits on OpenBot's answer, and a decision can wait in the queue behind a connect or Desktop's
* connect: either way another origin may have replaced the pending connect by now, and that newer one, with its open
* tab, is left alone. The check and the clear are one queued job, so no connect lands between them. A Cancel is kept
* for the origin that asked, so its page hears it (`connectStatus`). */
function clearPendingConnect(
decided: PendingConnect,
how: { cancelled?: true } = {},
): Promise<void> {
return serially(async () => {
const stored = await readSession("pendingConnect");
if (stored?.origin !== decided.origin || stored.code !== decided.code)
return;
await removeSession("pendingConnect");
if (how.cancelled)
await writeSession("cancelledConnect", {
origin: decided.origin,
at: Date.now(),
});
});
}
async function tabIsOpen(tabId: number | undefined): Promise<boolean> {
if (tabId === undefined) return false;
try {
await chrome.tabs.get(tabId);
return true;
} catch {
return false;
}
}
/** A connect page reads the pending origin once, on load. So the tab of a pending connect being replaced is closed
* first, or it would go on showing a site that is no longer pending (its decide names that site, and is refused).
* Best effort: a tab the person closed in the meantime leaves nothing to close. */
async function closeConnectTab(tabId: number | undefined): Promise<void> {
if (tabId === undefined) return;
try {
await chrome.tabs.remove(tabId);
} catch {
// Closed already.
}
}
/** openbot.ping and openbot.connect from OpenBot's web page. The origin is only ever the one Chrome reports. */
export async function handleExternalConnect(
message: ExternalToBackground,
sender: chrome.runtime.MessageSender,
deps?: Partial<ConnectionDeps>,
): Promise<ExternalResponse> {
const resolved = withDefaults(deps);
const origin = sender.origin;
if (message.type === "openbot.ping") return ping(origin);
if (message.type === RECORDER_CONNECT_STATUS) return connectStatus(origin);
if (message.type !== "openbot.connect")
return { ok: false, error: "invalid" };
if (!origin) return { ok: false, error: "invalid" };
const checked = normaliseOpenBotOrigin(origin);
if (!checked.ok) return { ok: false, error: "not-https" };
const policy = await resolved.readPolicy();
if (policy.openbotUrlInvalid) return { ok: false, error: "policy-invalid" };
if (policy.openbotUrl && !sameOrigin(policy.openbotUrl, checked.origin))
return { ok: false, error: "pinned-elsewhere" };
// Counted before anything else is done for it. Asking OpenBot Desktop for its address starts its native host, which
// looks for OpenBot's own port with lsof or netstat, and any page on a loopback port can ask to connect: counted
// after, a page asking over and over had the Recorder start that host as often as it liked.
const throttled = await serially(() =>
countConnect(checked.origin, Date.now()),
);
if (throttled) return throttled;
// A trusted OpenBot connects with no Connect page, and only while this browser is connected to nothing: replacing a
// connection (to another OpenBot, or for another person) always asks the person on the Connect page, which names the
// connection it replaces. Every other site keeps the one Connect click. Only an http origin can be OpenBot Desktop's
// (its local stack serves plain http on a loopback address), so only then is OpenBot Desktop asked for its address.
if ((await currentConnection()) === null) {
const desktop =
policy.openbotUrl !== checked.origin &&
new URL(checked.origin).protocol === "http:"
? await resolved.desktopAddress()
: null;
if (trustedConnectRule(policy, checked.origin, desktop) !== null)
return trustedConnect(checked.origin, message.code, resolved);
}
return serially(() => webConnect(checked.origin, message.code, resolved));
}
/**
* Which `openbot.connect` the Recorder takes with no Connect page (shared/recorder-page.ts, David 2026-10-22: "only for
* trusted OpenBots"): one from the OpenBot the organization's policy pins (`policy-pinned`), or from OpenBot Desktop's
* own address on this computer (`loopback-desktop`). OpenBot Desktop's address is `desktop`, the one its native host
* confirmed (native-host.ts `desktopAddress`), and only that exact origin is trusted: any program on this computer, a
* dev server or a notebook among them, can serve a page on a loopback port, so a loopback origin alone proves nothing.
* https on a loopback IP is never OpenBot Desktop's local stack, which serves plain http. Null for every other origin,
* for one the policy does not allow, and for every loopback origin when OpenBot Desktop confirmed none.
*/
export function trustedConnectRule(
policy: RecorderPolicy,
origin: string,
desktop: string | null,
): TrustedConnectRule | null {
const checked = normaliseOpenBotOrigin(origin);
if (!checked.ok || !allowsOpenBot(policy, checked.origin)) return null;
if (policy.openbotUrl === checked.origin) return "policy-pinned";
if (new URL(checked.origin).protocol !== "http:" || desktop === null)
return null;
const confirmed = normaliseOpenBotOrigin(desktop);
return confirmed.ok && confirmed.origin === checked.origin
? "loopback-desktop"
: null;
}
/** Counts a web connect from `origin` against its limit, in the caller's queued job: the refusal when it is over it,
* else null. */
async function countConnect(
origin: string,
now: number,
): Promise<ExternalResponse | null> {
const requests = await readSession("connectRequests");
const recent = (requests?.[origin] ?? []).filter(
(at) => now - at < CONNECT_WINDOW_MS,
);
// Not "busy": nothing is pending, and the wait is until the oldest of these leaves the window, which the page says.
if (recent.length >= CONNECT_LIMIT)
return {
ok: false,
error: "throttled",
retryAfterMs: Math.min(...recent) + CONNECT_WINDOW_MS - now,
};
await writeSession("connectRequests", {
...requests,
[origin]: [...recent, now],
});
return null;
}
/**
* A trusted OpenBot's connect (`trustedConnectRule`), with no Connect page: the person is already in that OpenBot,
* signed in, asking, and this browser is connected to nothing. Otherwise it is what an approved Connect is, as OpenBot
* Desktop's connect is: counted against the same limit (by `handleExternalConnect`, first); its code exchanged at the origin Chrome reported, under this
* copy's install id for it and the browser's own name; the connection stored in a queued job that checks the policy
* again and that nothing was connected meanwhile (a token either keeps out is revoked: a connection that landed during
* the exchange is never replaced without the Connect page, and the page asking again gets that page); a Connect page
* still open closed, since approving it would replace this connection; and the signed-out notice gone. The router then
* does an approved Connect's follow-up, as the answer says it connected.
*/
async function trustedConnect(
origin: string,
code: string,
deps: ConnectionDeps,
): Promise<ExternalResponse> {
let exchanged: ExchangeResponse;
try {
exchanged = await openbotJson<ExchangeResponse>(
{ openbotUrl: origin },
recorderPaths.connections,
{
body: {
code,
label: defaultBrowserName(),
installId: await installIdFor(origin),
},
signal: AbortSignal.timeout(DESKTOP_EXCHANGE_WAIT_MS),
},
);
} catch (error) {
return {
ok: false,
error:
error instanceof OpenBotError
? "exchange-refused"
: "openbot-unreachable",
};
}
const connection: ConnectionRecord = {
openbotUrl: origin,
token: exchanged.token,
connectionId: exchanged.connection.id,
user: exchanged.user,
via: "web",
connectedAt: Date.now(),
};
const kept = await serially(async (): Promise<ExternalResponse | null> => {
if (!allowsOpenBot(await deps.readPolicy(), origin))
return { ok: false, error: "pinned-elsewhere" };
if ((await currentConnection()) !== null)
return { ok: false, error: "busy" };
await writeLocal("connection", connection);
const pending = await readSession("pendingConnect");
if (pending) {
await closeConnectTab(pending.tabId);
await removeSession("pendingConnect");
}
return null;
});
if (kept) {
await revoke(connection);
return kept;
}
if ((await readLocal("notice"))?.kind === "signed-out")
await removeLocal("notice");
return {
ok: true,
version: chrome.runtime.getManifest().version,
installId: await installIdFor(origin),
connected: true,
};
}
/** Everything from the pending connect through the connect tab, in one queued job (see `serially`); the request was
* counted already, as every connect is first (`handleExternalConnect`). */
async function webConnect(
origin: string,
code: string,
deps: ConnectionDeps,
): Promise<ExternalResponse> {
const now = Date.now();
const pending = await readSession("pendingConnect");
if (pending && (await tabIsOpen(pending.tabId))) {
// Whatever the pending connect's age, so no page can open more than one connect tab however often it asks.
if (pending.origin === origin) {
await writeSession("pendingConnect", {
...pending,
code,
requestedAt: now,
});
await chrome.tabs.update(pending.tabId as number, { active: true });
return AWAITING_CONFIRMATION;
}
if (now - pending.requestedAt < PENDING_MAX_AGE_MS)
return { ok: false, error: "busy" };
await closeConnectTab(pending.tabId);
}
const next: PendingConnect = {
origin,
code,
via: "web",
requestedAt: now,
};
await writeSession("pendingConnect", next);
// A new request from the origin that cancelled before is waiting again.
if ((await readSession("cancelledConnect"))?.origin === origin)
await removeSession("cancelledConnect");
const tabId = await deps.openTab(connectUrl());
if (tabId !== undefined)
await writeSession("pendingConnect", { ...next, tabId });
return AWAITING_CONFIRMATION;
}
/**
* Version and install id only to the connected origin (Decision 22): every other site hears the same bare answer, a
* site with a connect waiting for the person's click included. The install id is stable for this copy and that origin,
* so handing it to a site that only asked would let that site know this browser again after its cookies are cleared.
*
* Even the bare answer says the Recorder is here, and so does Chrome itself, to every page `externally_connectable`
* lets in: a page that sends a message to an id with no extension behind it, or to one that does not let that page in,
* hears "Could not establish connection. Receiving end does not exist." (Chromium's message_service.cc does that on
* purpose, so a page it refuses cannot tell), while a page an installed extension lets in hears an answer, or "The
* message port closed before a response was received." when it gives none (both seen in Chrome 151). The Recorder lets
* in every page, since any OpenBot, at any address, may ask to connect: silence would hide nothing, and OpenBot's own
* page, which a Recorder not yet connected to it must answer, would be left reading Chrome's error text.
*/
async function ping(origin: string | undefined): Promise<ExternalResponse> {
if (!origin) return { ok: true };
const connection = await currentConnection();
if (connection?.openbotUrl !== origin) return { ok: true };
return {
ok: true,
version: chrome.runtime.getManifest().version,
installId: await installIdFor(origin),
};
}
/**
* Where the asking origin's own web connect has got to (shared/recorder-page.ts `RecorderConnectWait`), for the page that
* waits on it: its Connect page open, cancelled there, or closed without a choice. Read from what the Recorder already
* keeps, asked of Chrome only for whether that tab is still open; it says nothing of any other origin's request, nor of
* this copy, so it tells a site no more than it caused itself.
*/
async function connectStatus(
origin: string | undefined,
): Promise<ExternalResponse> {
const checked = origin ? normaliseOpenBotOrigin(origin) : null;
if (!checked?.ok) return { ok: true, connect: "none" };
const pending = await readSession("pendingConnect");
if (pending?.via === "web" && pending.origin === checked.origin)
return {
ok: true,
connect: (await tabIsOpen(pending.tabId)) ? "waiting" : "closed",
};
// A Cancel is news only while a page could still be waiting on it: within the five minutes a request lasts, and before
// that origin connected by any other way (a trusted OpenBot's connect, OpenBot Desktop's). It was kept for the whole
// browser session, and only a new web connect from the same origin took it away.
const cancelled = await readSession("cancelledConnect");
if (cancelled?.origin !== checked.origin)
return { ok: true, connect: "none" };
const stale =
Date.now() - cancelled.at >= PENDING_MAX_AGE_MS ||
(await currentConnection())?.openbotUrl === checked.origin;
if (stale) {
await serially(async () => {
if ((await readSession("cancelledConnect"))?.at === cancelled.at)
await removeSession("cancelledConnect");
});
return { ok: true, connect: "none" };
}
return { ok: true, connect: "cancelled" };
}
function sameOrigin(raw: string, origin: string): boolean {
const checked = normaliseOpenBotOrigin(raw);
return checked.ok && checked.origin === origin;
}
/** Best effort: OpenBot revokes the token (the person can also revoke it in OpenBot). */
async function revoke(connection: ConnectionRecord): Promise<void> {
try {
await openbotJson(connection, recorderPaths.currentConnection, {
method: "DELETE",
});
} catch {
// Unreachable, or already revoked.
}
}
/** Compares the stored connection with the policy: a policy that pins another origin, or is invalid, forgets the
* connection and leaves a `policy-moved` notice (its origin empty for an invalid policy), then stops what the connection
* still has running (the live recording, and whatever the document sends with its token; everything recorded is kept
* for its person) and revokes the token. Called at every start and on every managed-storage change. The token check
* keeps a reconnect that lands meanwhile. */
async function reconcilePolicy(deps: ConnectionDeps): Promise<void> {
const policy = await deps.readPolicy();
const connection = await currentConnection();
if (!connection || allowsOpenBot(policy, connection.openbotUrl)) return;
const moved = policy.openbotUrlInvalid ? "" : (policy.openbotUrl ?? "");
if (!(await forgetConnection("disconnected", connection.token))) return;
await writeLocal("notice", {
kind: "policy-moved",
at: Date.now(),
origin: moved,
});
await deps.connectionLost({ kind: "policy", connection });
await revoke(connection);
}
/** Whether OpenBot Desktop connected this browser, or why not, as a code the popup turns into a sentence: OpenBot
* Desktop's own error code (see DesktopRefusal); `policy-invalid`, `pinned-elsewhere` or `invalid-address` from the
* checks here; `exchange-refused` or `openbot-unreachable` when OpenBot did not take Desktop's code; or `launched` when
* the Recorder's launcher connects this browser instead (an install's own connect only). */
export type DesktopConnect =
| { connected: true }
| { connected: false; reason: string };
/**
* Connects this browser through OpenBot Desktop's native host, with no Connect page: the code comes from OpenBot Desktop
* on this computer, which only the Recorder can ask (the host answers only the Recorder's own extension origin), so
* there is no web page's request to confirm. The checks are a web connect's (OpenBot's address rule and the
* organization's policy), and the rest is what an approved Connect does: the code is exchanged at that OpenBot under
* this copy's install id, the connection is stored in a queued job that checks the policy again (a token it keeps out
* is revoked), and the signed-out notice goes. The caller then does an approved Connect's follow-up (`connected`).
*
* A managed browser connects only where its policy points, on the Desktop path too. Desktop's local stack is always a
* loopback http address, so a policy naming any other kind of address can never match and Desktop is not asked.
*/
export function connectThroughDesktop(
deps?: Partial<ConnectionDeps>,
options: { install?: boolean } = {},
): Promise<DesktopConnect> {
const resolved = withDefaults(deps);
return serially(() => desktopConnect(resolved, options.install === true));
}
async function desktopConnect(
deps: ConnectionDeps,
install: boolean,
): Promise<DesktopConnect> {
const refused = (reason: string): DesktopConnect => ({
connected: false,
reason,
});
// An OpenBot browser's launcher connected it, or is connecting it (`connectFromLauncher`): the connect an install
// makes on its own would put a second connection in a browser that needs none. Asked before Desktop is asked, and
// again before the connection is stored, since on a first launch the launcher's connection arrives while Desktop
// answers. The person's own choice from the popup is left alone.
const launched = async () =>
install &&
(launcherConnecting > 0 ||
(await currentConnection())?.via === "openbot-browser");
if (await launched()) return refused("launched");
const policy = await deps.readPolicy();
if (policy.openbotUrlInvalid) return refused("policy-invalid");
if (policy.openbotUrl && !policy.openbotUrl.startsWith("http:"))
return refused("pinned-elsewhere");
const handoff = await deps.askDesktop();
if (!handoff) return refused("no-answer");
if ("error" in handoff) return refused(handoff.error);
const checked = normaliseOpenBotOrigin(handoff.openbotUrl);
if (!checked.ok) return refused("invalid-address");
if (!allowsOpenBot(policy, checked.origin))
return refused("pinned-elsewhere");
if (await launched()) return refused("launched");
let exchanged: ExchangeResponse;
try {
exchanged = await openbotJson<ExchangeResponse>(
{ openbotUrl: checked.origin },
recorderPaths.connections,
{
body: {
code: handoff.code,
label: defaultBrowserName(),
installId: await installIdFor(checked.origin),
},
signal: AbortSignal.timeout(DESKTOP_EXCHANGE_WAIT_MS),
},
);
} catch (error) {
return refused(
error instanceof OpenBotError
? "exchange-refused"
: "openbot-unreachable",
);
}
const connection: ConnectionRecord = {
openbotUrl: checked.origin,
token: exchanged.token,
connectionId: exchanged.connection.id,
user: exchanged.user,
via: "desktop",
connectedAt: Date.now(),
};
// This job is the queued one that stores it: the launcher's connection, or a pin elsewhere, that came while OpenBot
// answered keeps it out, and the token OpenBot just made is revoked.
const keptOut = (await launched())
? "launched"
: !allowsOpenBot(await deps.readPolicy(), checked.origin)
? "pinned-elsewhere"
: null;
if (keptOut) {
await revoke(connection);
return refused(keptOut);
}
const replaced = await currentConnection();
await writeLocal("connection", connection);
await endReplaced(replaced, connection, deps);
// A Connect page still open would replace this connection if the person approved it: it closes, and nothing is pending.
const pending = await readSession("pendingConnect");
if (pending) {
await closeConnectTab(pending.tabId);
await removeSession("pendingConnect");
}
if ((await readLocal("notice"))?.kind === "signed-out")
await removeLocal("notice");
return { connected: true };
}