Files
Netcatty/electron/plugins/hostInteractionService.cjs
T

428 lines
22 KiB
JavaScript

"use strict";
const { createHmac, randomBytes, randomUUID, timingSafeEqual } = require("node:crypto");
const { createDefinitionValidator } = require("./contractValidator.cjs");
const { TerminalSelectionAuthority } = require("./terminalSelectionAuthority.cjs");
const { PluginRpcError, RPC_ERRORS } = require("./rpcRouter.cjs");
const schema = require("./generated/plugin-contract.schema.json");
const LIMITS = schema.$defs.HostInteractionLimits.const;
const HOST_INTERACTION_FEATURE = schema.$defs.HostInteractionFeature.const;
const validateRequest = createDefinitionValidator("HostInteractionRequest");
const validateResponse = createDefinitionValidator("HostInteractionResponse");
const validateResult = createDefinitionValidator("HostInteractionResult");
const validateSingleLineInput = createDefinitionValidator("HostSingleLineInputText");
const PROMPT_CHANNEL = "netcatty:plugins:host-interaction";
function fail(code, message) { return new PluginRpcError(RPC_ERRORS[code], message); }
function assertTextBytes(text) {
if (typeof text !== "string" || Buffer.byteLength(text, "utf8") > LIMITS.textBytes || text.includes("\0")) {
throw fail("resourceExhausted", "Host interaction text exceeds its limit");
}
return text;
}
function assertInteractionRequest(params) {
if (!validateRequest(params)) throw fail("invalidArgument", "Host interaction request is invalid");
if (Buffer.byteLength(JSON.stringify(params)) > LIMITS.requestBytes) {
throw fail("resourceExhausted", "Host interaction request exceeds its limit");
}
if (params.kind === "input") assertTextBytes(params.initialValue ?? "");
if (params.kind === "clipboard.write") assertTextBytes(params.text);
if (params.kind === "terminal.input.propose" && Buffer.byteLength(params.text, "utf8") > LIMITS.textBytes) throw fail("resourceExhausted", "Terminal input draft exceeds its limit");
if (params.kind === "quickPick" && new Set(params.items.map((item) => item.id)).size !== params.items.length) {
throw fail("invalidArgument", "Host interaction choice IDs must be unique");
}
return Object.freeze(structuredClone(params));
}
function interactionAuthorization(params, terminalTarget) {
if (params.kind === "terminal.selection.read" || params.kind === "terminal.input.propose") {
if (!terminalTarget) throw fail("failedPrecondition", "A host-selected terminal is required");
return { permission: params.kind, resources: [terminalTarget.resource],
reason: params.kind === "terminal.selection.read" ? "Preview and explicitly share the selected terminal text" : "Open an editable host draft without sending terminal input", operationId: params.kind, allowedScopes: ["once"] };
}
const permission = params.kind === "clipboard.read" ? "clipboard.read"
: params.kind === "clipboard.write" ? "clipboard.write" : "ui.interact";
return {
permission,
resources: [permission.startsWith("clipboard.") ? "clipboard:text" : "*"],
reason: permission.startsWith("clipboard.") ? "Explicitly share or replace clipboard text" : "Show a host input or choice dialog",
operationId: `ui:${params.kind}`,
...(permission.startsWith("clipboard.") ? { allowedScopes: ["once"] } : {}),
};
}
class PluginHostInteractionService {
constructor(options) {
this.database = options.database;
this.permissionEngine = options.permissionEngine;
this.quotaManager = options.quotaManager;
this.clipboard = options.clipboard;
this.getWindow = options.getWindow ?? (() => null);
this.isLocked = options.isLocked ?? (() => true);
this.clock = options.clock ?? Date.now;
this.timeoutMs = Math.min(options.timeoutMs ?? LIMITS.timeoutMs, LIMITS.timeoutMs);
this.key = randomBytes(32);
this.pending = new Map();
this.terminalSelection = new TerminalSelectionAuthority({database: this.database, getWindow: this.getWindow, getManager: options.getTerminalWorkerManager, clock: this.clock});
this.terminalInvalidation = this.terminalSelection.onDidInvalidate(() => {
for (const entry of [...this.pending.values()]) if (entry.terminalTarget && !this.#terminalCurrent(entry)) {
this.#finish(entry, null, fail("cancelled", "Selected terminal connection changed"));
}
});
this.rates = new Map();
this.admissions = new WeakMap();
this.admissionGuards = new Map();
this.admissionRevision = 0;
this.focusRestoreMs = Math.min(options.focusRestoreMs ?? 1_000, 1_000);
this.owner = null;
this.ownerGeneration = 0;
this.ownerCleanup = null;
this.closed = false;
this.revocation = this.permissionEngine.onDidRevoke((event) => this.releasePlugin(event.pluginId));
this.unsubscribeLock = options.subscribeLock?.((state) => { if (state.locked) this.cancelAll(); });
}
#terminalCurrent(entry) {
if (!this.terminalSelection.isCurrent(entry.terminalTarget)) return false;
if (entry.params.kind === "terminal.input.propose") {
try { this.terminalSelection.resolve(entry.params.handle, entry.context); } catch { return false; }
}
return true;
}
registerRpcCapabilities(registry) {
registry.registerRequest("ui.interact", (params, context) => this.request(params, context), {
metadata: { capability: "ui", mutating: true },
validateParams: assertInteractionRequest,
authorization: (params, context) => {
const admission = this.admitRequest(params, context);
return interactionAuthorization(params, admission.terminalTarget);
},
});
}
admitRequest(params, context) {
const sender = this.#admit(params, context);
let guard = this.admissionGuards.get(context.runtimeId);
if (!guard) { guard = { active: true }; this.admissionGuards.set(context.runtimeId, guard); }
const terminalTarget = params.kind === "terminal.selection.read" ? this.terminalSelection.capture(sender, context)
: params.kind === "terminal.input.propose" ? this.terminalSelection.resolve(params.handle, context) : undefined;
const admission = { sender, runtimeId: context.runtimeId, revision: this.admissionRevision, guard, terminalTarget };
this.admissions.set(params, admission);
return admission;
}
setReady(sender, ready) {
const window = this.getWindow();
if (!sender || window?.webContents !== sender || sender.isDestroyed?.()) {
throw fail("permissionDenied", "Host interaction window is not the owner");
}
if (typeof ready !== "boolean") throw fail("invalidArgument", "Host interaction readiness is invalid");
if (!ready) { this.releaseWindow(sender); return true; }
if (this.closed) throw fail("unavailable", "Host interactions are unavailable");
if (this.owner === sender) return true;
if (this.owner) this.releaseWindow(this.owner);
this.owner = sender;
this.ownerGeneration++;
const close = () => this.releaseWindow(sender);
// A native permission dialog can temporarily blur its parent. Already
// displayed interactions still cancel immediately; pre-prompt admission
// can only resume once this same owner actually regains focus.
const blur = () => this.cancelAll(false);
const hide = () => this.cancelAll();
const navigate = (details, _url, isInPlace, isMainFrame) => {
const main = details?.isMainFrame ?? isMainFrame;
const sameDocument = details?.isSameDocument ?? isInPlace;
if (main !== false && sameDocument !== true) close();
};
sender.once?.("destroyed", close);
sender.on?.("did-start-navigation", navigate);
sender.on?.("render-process-gone", close);
window.on?.("blur", blur);
window.on?.("hide", hide);
this.ownerCleanup = () => {
sender.removeListener?.("destroyed", close);
sender.removeListener?.("did-start-navigation", navigate);
sender.removeListener?.("render-process-gone", close);
window.removeListener?.("blur", blur);
window.removeListener?.("hide", hide);
};
return true;
}
#assertWindow(sender = this.owner) {
const window = this.getWindow();
if (this.closed || this.isLocked() || !sender || sender !== this.owner
|| window?.webContents !== sender || window.isDestroyed?.()
|| sender.isDestroyed?.() || window.isVisible?.() === false || window.isFocused?.() !== true) {
throw fail("unavailable", "Host interactions require the focused unlocked main window");
}
return sender;
}
#token(entry) {
const nonce = randomBytes(24).toString("base64url");
const binding = JSON.stringify([
nonce, entry.id, entry.context.pluginId, entry.context.pluginVersion,
entry.context.runtimeId, entry.sender.id, entry.params.kind, entry.phase, entry.expiresAt, entry.terminalTarget?.resource ?? null,
]);
return `${nonce}.${createHmac("sha256", this.key).update(binding).digest("base64url")}`;
}
#present(entry) {
entry.actionToken = this.#token(entry);
entry.sender.send(PROMPT_CHANNEL, {
requestId: entry.id, actionToken: entry.actionToken,
pluginId: entry.context.pluginId, pluginVersion: entry.context.pluginVersion,
expiresAt: entry.expiresAt, phase: entry.phase, request: entry.params,
...(entry.terminalTarget ? { terminalSessionId: entry.terminalTarget.sessionId, terminalRendererId: entry.terminalTarget.rendererId, terminalLabel: entry.terminalTarget.label } : {}),
...(entry.previewText === undefined ? {} : { previewText: entry.previewText }),
...(this.vaultService?.isRequest(entry.params) ? this.vaultService.describePrompt(entry) : {}),
...(entry.reviewedDraft === undefined ? {} : { reviewedDraft: entry.reviewedDraft }),
});
}
#finish(entry, result, error) {
if (this.pending.get(entry.id) !== entry) return false;
this.pending.delete(entry.id);
entry.actionToken = null;
entry.previewText = undefined;
clearTimeout(entry.timer);
entry.context.signal?.removeEventListener("abort", entry.onAbort);
try { entry.sender.send(PROMPT_CHANNEL, { requestId: entry.id, closed: true }); } catch {}
if (error) entry.reject(error);
else if (!validateResult(result)) entry.reject(fail("internal", "Host interaction result is invalid"));
else entry.resolve(result);
return true;
}
#audit(entry, action) {
// Fixed metadata only. Never record title, choices, user input, clipboard
// bytes, action token or a hash derived from user content.
try {
this.database.recordSecurityAudit(entry.context.pluginId, "ui.interaction", { kind: entry.params.kind, action });
} catch {
throw fail("unavailable", "Host interaction audit is unavailable");
}
}
#admit(params, context) {
const sender = this.#assertWindow();
if ((params.kind === "clipboard.read" && typeof this.clipboard?.readText !== "function")
|| (params.kind === "clipboard.write" && typeof this.clipboard?.writeText !== "function")) {
throw fail("unavailable", "Host clipboard text is unavailable");
}
const now = this.clock();
const rate = this.rates.get(context.runtimeId);
const nextRate = !rate || now - rate.startedAt >= 60_000 ? { startedAt: now, count: 0 } : rate;
if (nextRate.count >= LIMITS.requestsPerMinute || this.pending.size >= LIMITS.pendingTotal
|| [...this.pending.values()].some((entry) => entry.context.runtimeId === context.runtimeId || entry.sender === sender)) {
throw fail("resourceExhausted", "Host interaction limit reached");
}
nextRate.count++;
this.rates.set(context.runtimeId, nextRate);
this.quotaManager.chargeBytes(context.runtimeId, "ui", Buffer.byteLength(JSON.stringify(params)));
return sender;
}
async request(params, context) {
await context.assertActive();
const admission = this.admissions.get(params);
this.admissions.delete(params);
let sender;
if (admission?.runtimeId === context.runtimeId) {
// Electron may resolve showMessageBox before restoring parent focus.
// Never focus it ourselves or defer an originally background request.
// Owner replacement, lock, hide, revoke and runtime stop invalidate this
// host-owned admission, including changes during the permission prompt.
const deadline = Date.now() + this.focusRestoreMs;
for (;;) {
context.signal?.throwIfAborted();
if (!admission.guard.active || admission.revision !== this.admissionRevision || admission.sender !== this.owner) {
throw fail("cancelled", "Host interaction admission was revoked");
}
const window = this.getWindow();
if (this.closed || this.isLocked() || window?.webContents !== admission.sender
|| window.isDestroyed?.() || admission.sender.isDestroyed?.() || window.isVisible?.() === false) {
throw fail("unavailable", "Host interaction owner is unavailable");
}
if (window.isFocused?.() === true) break;
if (Date.now() >= deadline) throw fail("unavailable", "Host interactions require the focused unlocked main window");
await new Promise((resolve) => setTimeout(resolve, Math.min(20, Math.max(1, deadline - Date.now()))));
}
await context.assertActive();
if (!admission.guard.active || admission.revision !== this.admissionRevision) throw fail("cancelled", "Host interaction admission was revoked");
sender = this.#assertWindow(admission.sender);
} else sender = this.#admit(params, context);
if (this.pending.size >= LIMITS.pendingTotal || [...this.pending.values()].some((entry) => entry.context.runtimeId === context.runtimeId || entry.sender === sender)) {
throw fail("resourceExhausted", "Host interaction limit reached");
}
const terminalTarget = admission?.terminalTarget ?? (params.kind === "terminal.selection.read"
? this.terminalSelection.capture(sender, context) : params.kind === "terminal.input.propose"
? this.terminalSelection.resolve(params.handle, context) : undefined);
if (terminalTarget) this.terminalSelection.assertCurrent(terminalTarget);
if (params.kind === "terminal.input.propose") this.terminalSelection.resolve(params.handle, context);
const now = this.clock();
return new Promise((resolve, reject) => {
const entry = {
id: randomUUID(), context, params, sender, resolve, reject, terminalTarget,
expiresAt: now + this.timeoutMs, phase: "request", actionToken: null,
};
entry.onAbort = () => this.#finish(entry, null, fail("cancelled", "Host interaction was cancelled"));
entry.timer = setTimeout(() => this.#finish(entry, null, fail("deadlineExceeded", "Host interaction expired")), this.timeoutMs);
entry.timer.unref?.();
this.pending.set(entry.id, entry);
context.signal?.addEventListener("abort", entry.onAbort, { once: true });
if (context.signal?.aborted) { entry.onAbort(); return; }
try { this.#present(entry); }
catch { this.#finish(entry, null, fail("unavailable", "Host interaction window is unavailable")); }
});
}
async respond(sender, response) {
this.#assertWindow(sender);
if (!validateResponse(response)) throw fail("invalidArgument", "Host interaction response is invalid");
const entry = this.pending.get(response.requestId);
if (!entry || entry.sender !== sender || !entry.actionToken || this.clock() >= entry.expiresAt) return false;
const expected = Buffer.from(entry.actionToken);
const supplied = Buffer.from(response.actionToken);
if (expected.length !== supplied.length || !timingSafeEqual(expected, supplied)) return false;
// Consume before the first asynchronous boundary. Duplicate and old-phase
// replies cannot race the same native action.
entry.actionToken = null;
try {
await entry.context.assertActive();
this.#assertWindow(sender);
if (this.pending.get(entry.id) !== entry) return false;
if (entry.terminalTarget) this.terminalSelection.assertCurrent(entry.terminalTarget);
if (entry.params.kind === "terminal.input.propose") this.terminalSelection.resolve(entry.params.handle, entry.context);
if (response.action === "cancel") {
this.#audit(entry, "cancelled");
return this.#finish(entry, { cancelled: true });
}
if (this.vaultService?.isRequest(entry.params)) {
const outcome = await this.vaultService.respond(entry, response);
await entry.context.assertActive();
this.#assertWindow(sender);
if (this.pending.get(entry.id) !== entry) return false;
if (outcome.result) {
this.#audit(entry, "completed");
return this.#finish(entry, outcome.result);
}
this.#audit(entry, outcome.phase === "commit" ? "action-confirmed" : "action-claimed");
entry.phase = outcome.phase;
if (outcome.reviewedDraft !== undefined) entry.reviewedDraft = outcome.reviewedDraft;
if (entry.phase === "executing") {
entry.actionToken = this.#token(entry);
return { completionToken: entry.actionToken };
}
this.#present(entry);
return true;
}
if (entry.params.kind === "terminal.selection.read" && entry.phase === "request") {
if (response.action !== "preview") throw fail("invalidArgument", "Terminal sharing requires a preview action");
const text = assertTextBytes(response.value);
if (!text.length) throw fail("failedPrecondition", "Select terminal text before requesting a share");
this.#audit(entry, "preview-confirmed");
this.quotaManager.chargeBytes(entry.context.runtimeId, "terminal", Buffer.byteLength(text));
entry.previewText = text; entry.phase = "preview"; this.#present(entry); return true;
}
if (entry.params.kind === "clipboard.read" && entry.phase === "request") {
if (response.action !== "preview") throw fail("invalidArgument", "Clipboard sharing requires a preview action");
this.#audit(entry, "preview-confirmed");
let rawText;
try { rawText = this.clipboard.readText(); }
catch { throw fail("unavailable", "Host clipboard text is unavailable"); }
const text = assertTextBytes(rawText);
this.quotaManager.chargeBytes(entry.context.runtimeId, "clipboard", Buffer.byteLength(text));
entry.previewText = text;
entry.phase = "preview";
try { this.#present(entry); }
catch { throw fail("unavailable", "Host interaction window is unavailable"); }
return true;
}
if (response.action !== "submit") throw fail("invalidArgument", "Host interaction action is invalid");
let value;
if (entry.params.kind === "input") {
if (!validateSingleLineInput(response.value)) throw fail("invalidArgument", "Host input must be a single line");
value = assertTextBytes(response.value);
}
else if (entry.params.kind === "quickPick") {
if (!entry.params.items.some((item) => item.id === response.value)) throw fail("invalidArgument", "Host interaction choice is invalid");
value = response.value;
} else if (entry.params.kind === "terminal.selection.read") {
if (entry.phase !== "preview" || typeof entry.previewText !== "string") throw fail("failedPrecondition", "Terminal selection was not previewed");
} else if (entry.params.kind === "clipboard.read") value = entry.previewText;
else value = true;
this.#audit(entry, entry.params.kind === "terminal.input.propose" ? "draft-reviewed" : entry.params.kind === "clipboard.write" ? "copy-confirmed" : "share-confirmed");
if (entry.params.kind === "terminal.selection.read") {
value = Object.freeze({ text: entry.previewText, ...this.terminalSelection.issue(entry.terminalTarget, entry.context) });
}
if (entry.params.kind === "clipboard.write") {
try { this.clipboard.writeText(entry.params.text); }
catch { throw fail("unavailable", "Host clipboard write failed"); }
}
return this.#finish(entry, { cancelled: false, value });
} catch (error) {
this.#finish(entry, null, error);
throw error;
}
}
setTerminalTarget(sender, target) { return this.terminalSelection.setTarget(sender, target); }
releaseWindow(sender) {
if (this.owner !== sender) return;
this.terminalSelection.releaseWindow(sender);
this.admissionRevision++;
this.ownerGeneration++;
this.vaultService?.clearSelections();
this.owner = null;
this.ownerCleanup?.(); this.ownerCleanup = null;
for (const entry of [...this.pending.values()]) {
if (entry.sender === sender) this.#finish(entry, null, fail("cancelled", "Host interaction window closed"));
}
}
releasePlugin(pluginId) {
this.terminalSelection.releasePlugin(pluginId);
this.admissionRevision++;
this.vaultService?.releasePlugin(pluginId);
for (const entry of [...this.pending.values()]) {
if (entry.context.pluginId === pluginId) this.#finish(entry, null, fail("cancelled", "Plugin access was revoked"));
}
}
releaseRuntime(runtimeId) {
this.terminalSelection.releaseRuntime(runtimeId);
this.cancelRuntimeRequests(runtimeId, "Plugin runtime stopped");
this.rates.delete(runtimeId);
this.vaultService?.releaseRuntime(runtimeId);
}
cancelRuntimeRequests(runtimeId, reason = "Host command finished") {
const guard = this.admissionGuards.get(runtimeId);
if (guard) guard.active = false;
this.admissionGuards.delete(runtimeId);
for (const entry of [...this.pending.values()]) {
if (entry.context.runtimeId === runtimeId) this.#finish(entry, null, fail("cancelled", reason));
}
}
cancelAll(invalidateAdmission = true) {
if (invalidateAdmission) {
this.admissionRevision++;
this.terminalSelection.clearHandles();
this.vaultService?.clearSelections();
}
for (const entry of [...this.pending.values()]) this.#finish(entry, null, fail("cancelled", "Host interaction was cancelled"));
}
shutdown() {
if (this.closed) return;
this.closed = true;
if (this.owner) this.releaseWindow(this.owner);
this.cancelAll(); this.rates.clear(); this.admissionGuards.clear();
this.revocation.dispose(); this.unsubscribeLock?.();
this.terminalInvalidation.dispose(); this.terminalSelection.shutdown();
this.key.fill(0);
this.vaultService?.shutdown();
}
}
module.exports = { HOST_INTERACTION_FEATURE, LIMITS, PROMPT_CHANNEL, PluginHostInteractionService, assertInteractionRequest, interactionAuthorization };