mirror of
https://github.com/binaricat/Netcatty.git
synced 2026-11-16 20:11:08 +00:00
340 lines
16 KiB
JavaScript
340 lines
16 KiB
JavaScript
"use strict";
|
|
|
|
const { createHmac, randomBytes, randomUUID, timingSafeEqual } = require("node:crypto");
|
|
const { createDefinitionValidator } = require("./contractValidator.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 === "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) {
|
|
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.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.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(); });
|
|
}
|
|
|
|
registerRpcCapabilities(registry) {
|
|
registry.registerRequest("ui.interact", (params, context) => this.request(params, context), {
|
|
metadata: { capability: "ui", mutating: true },
|
|
validateParams: assertInteractionRequest,
|
|
authorization: (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); }
|
|
this.admissions.set(params, { sender, runtimeId: context.runtimeId, revision: this.admissionRevision, guard });
|
|
return interactionAuthorization(params);
|
|
},
|
|
});
|
|
}
|
|
|
|
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;
|
|
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,
|
|
]);
|
|
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.previewText === undefined ? {} : { previewText: entry.previewText }),
|
|
});
|
|
}
|
|
|
|
#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 now = this.clock();
|
|
return new Promise((resolve, reject) => {
|
|
const entry = {
|
|
id: randomUUID(), context, params, sender, resolve, reject,
|
|
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 (response.action === "cancel") {
|
|
this.#audit(entry, "cancelled");
|
|
return this.#finish(entry, { cancelled: 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 === "clipboard.read") value = entry.previewText;
|
|
else value = true;
|
|
this.#audit(entry, entry.params.kind === "clipboard.write" ? "copy-confirmed" : "share-confirmed");
|
|
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;
|
|
}
|
|
}
|
|
|
|
releaseWindow(sender) {
|
|
if (this.owner !== sender) return;
|
|
this.admissionRevision++;
|
|
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.admissionRevision++;
|
|
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.cancelRuntimeRequests(runtimeId, "Plugin runtime stopped");
|
|
this.rates.delete(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++;
|
|
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.key.fill(0);
|
|
}
|
|
}
|
|
|
|
module.exports = { HOST_INTERACTION_FEATURE, LIMITS, PROMPT_CHANNEL, PluginHostInteractionService, assertInteractionRequest, interactionAuthorization };
|