Build your personal knowledge base with Trilium Notes
TypeScript electronelectron-appknowledge-baseknowledge-graphknowledge-managementknowledge-management-graphlocal-firstnote-managmentnote-takernote-takingnotebooknotesnotes-apppersonal-knowledge-basepersonal-wikiscriptableself-hostedself-hostingwiki
import { once } from "node:events";
import express from "express";
import multer from "multer";
import { describe, expect, it, vi } from "vitest";
const electronMock = vi.hoisted(() => ({
registerSchemesAsPrivileged: vi.fn(),
handle: vi.fn(),
onBeforeRequest: vi.fn()
}));
vi.mock("electron", () => ({
default: {
app: { whenReady: () => Promise.resolve() },
protocol: { handle: electronMock.handle },
session: { defaultSession: { webRequest: { onBeforeRequest: electronMock.onBeforeRequest } } }
},
protocol: { registerSchemesAsPrivileged: electronMock.registerSchemesAsPrivileged }
}));
const { dispatch, isDispatchOriginAllowed, isRequestorChainTrusted, registerTriliumAppScheme, setupTriliumAppProtocol } = await import("./protocol.js");
const { isInternalElectronRequest } = await import("@triliumnext/server/src/services/electron_request.js");
function buildTestApp() {
const app = express();
app.use(express.json());
const upload = multer().single("upload");
app.post("/upload", upload, (req, res) => {
res.json({
field: (req.body as Record<string, unknown>)?.note,
filename: req.file?.originalname,
size: req.file?.size,
content: req.file?.buffer?.toString("utf-8")
});
});
app.post("/echo-json", (req, res) => {
res.json({ echo: req.body });
});
return app;
}
describe("trilium-app protocol dispatcher", () => {
it("forwards multipart/form-data through multer so handlers see req.file", async () => {
const app = buildTestApp();
const formData = new FormData();
formData.append("upload", new Blob(["hello world"], { type: "text/plain" }), "hello.txt");
formData.append("note", "abc123");
const request = new Request("trilium-app://app/upload", { method: "POST", body: formData });
const response = await dispatch(app, request);
expect(response.status).toBe(200);
expect(await response.json()).toEqual({
field: "abc123",
filename: "hello.txt",
size: 11,
content: "hello world"
});
});
it("forwards application/json bodies as parsed objects", async () => {
const app = buildTestApp();
const request = new Request("trilium-app://app/echo-json", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ hello: "world" })
});
const response = await dispatch(app, request);
expect(response.status).toBe(200);
expect(await response.json()).toEqual({ echo: { hello: "world" } });
});
// Auth + CSRF middleware rely on this marker to distinguish a
// renderer→main protocol dispatch from a public-HTTP request hitting the
// desktop's TCP listener. Regression for the auth bypass that used to
// key off the process-wide `isElectron` flag.
it("tags dispatched requests with the internal-electron marker", async () => {
const app = express();
let markedOnHandler: boolean | undefined;
app.get("/probe", (req, res) => {
markedOnHandler = isInternalElectronRequest(req);
res.status(200).send("");
});
await dispatch(app, new Request("trilium-app://app/probe"));
expect(markedOnHandler).toBe(true);
});
// SSE / streaming endpoints (e.g. LLM chat) commit headers up front with
// `res.flushHeaders()` and then write chunks over time. The bridge must
// (a) not crash on flushHeaders — Express rewires `res.__proto__` to the
// real ServerResponse, whose internal `outputData` was never initialised
// on the mock — and (b) deliver subsequent `res.write` chunks to the
// renderer in real time instead of buffering until `res.end`.
it("streams chunks to the renderer as soon as flushHeaders is called", async () => {
const app = express();
let resolveWriteGate: (() => void) | undefined;
const writeGate = new Promise<void>((r) => { resolveWriteGate = r; });
app.get("/stream", async (_req, res) => {
res.setHeader("Content-Type", "text/event-stream");
res.flushHeaders();
res.write("first\n");
// Hold the second chunk until the test confirms the first was
// already readable from the Response body — proving real-time
// delivery instead of buffer-then-flush.
await writeGate;
res.write("second\n");
res.end();
});
const dispatched = dispatch(app, new Request("trilium-app://app/stream"));
const response = await dispatched;
expect(response.status).toBe(200);
expect(response.headers.get("content-type")).toBe("text/event-stream");
const reader = response.body!.getReader();
const decoder = new TextDecoder();
const first = await reader.read();
expect(decoder.decode(first.value)).toBe("first\n");
resolveWriteGate!();
let rest = "";
while (true) {
const { done, value } = await reader.read();
if (done) break;
rest += decoder.decode(value);
}
expect(rest).toBe("second\n");
});
// `res.flush()` is the second crash vector from Express's prototype swap:
// some compression / response-time middleware probes it to force-flush,
// which would otherwise dereference uninitialised ServerResponse internals.
it("does not crash when handlers probe res.flush()", async () => {
const app = express();
app.get("/probe", (_req, res) => {
(res as unknown as { flush: () => void }).flush();
res.send("ok");
});
const response = await dispatch(app, new Request("trilium-app://app/probe"));
expect(response.status).toBe(200);
expect(await response.text()).toBe("ok");
});
it("delivers a final chunk passed to res.end() in streaming mode", async () => {
const app = express();
app.get("/stream", (_req, res) => {
res.setHeader("Content-Type", "text/event-stream");
res.flushHeaders();
res.write("part1\n");
res.end("part2\n");
});
const response = await dispatch(app, new Request("trilium-app://app/stream"));
expect(await response.text()).toBe("part1\npart2\n");
});
it("captures the status code at flushHeaders time for streaming responses", async () => {
const app = express();
app.get("/stream", (_req, res) => {
res.status(202);
res.flushHeaders();
res.end("body");
});
const response = await dispatch(app, new Request("trilium-app://app/stream"));
expect(response.status).toBe(202);
expect(await response.text()).toBe("body");
});
it("treats repeated flushHeaders() calls as idempotent", async () => {
const app = express();
app.get("/stream", (_req, res) => {
res.setHeader("Content-Type", "text/event-stream");
res.flushHeaders();
res.flushHeaders(); // no-op
res.write("hi");
res.end();
});
const response = await dispatch(app, new Request("trilium-app://app/stream"));
expect(response.status).toBe(200);
expect(await response.text()).toBe("hi");
});
// When the renderer aborts the fetch (user hits stop, tab navigates, ...),
// the bridge must error the stream so reads reject. Otherwise the upstream
// handler keeps writing into a closed channel and the renderer hangs.
it("errors the streaming body when the renderer aborts the fetch", async () => {
const app = express();
app.get("/stream", (_req, res) => {
res.setHeader("Content-Type", "text/event-stream");
res.flushHeaders();
res.write("first\n");
// Intentionally do not call res.end — the abort must tear down.
});
const abortController = new AbortController();
const request = new Request("trilium-app://app/stream", { signal: abortController.signal });
const response = await dispatch(app, request);
const reader = response.body!.getReader();
const first = await reader.read();
expect(new TextDecoder().decode(first.value)).toBe("first\n");
abortController.abort();
await expect(reader.read()).rejects.toThrow();
});
it("applies backpressure: res.write() returns false once the unread queue exceeds the high-water mark", async () => {
const app = express();
const writeResults: boolean[] = [];
app.get("/bp", (_req, res) => {
res.setHeader("Content-Type", "application/octet-stream");
res.flushHeaders();
// Write several 1 MiB chunks synchronously while nothing reads the
// body. Without backpressure these would all be buffered and return
// true; with it, the queue fills and writes start returning false.
for (let i = 0; i < 6; i++) {
writeResults.push(res.write(Buffer.alloc(1024 * 1024, i)));
}
res.end();
});
const response = await dispatch(app, new Request("trilium-app://app/bp"));
expect(writeResults).toContain(false);
// Backpressure is advisory: every chunk is still delivered intact.
const body = response.body;
if (!body) throw new Error("expected a streaming body");
const reader = body.getReader();
let total = 0;
while (true) {
const { done, value } = await reader.read();
if (done) break;
total += value?.length ?? 0;
}
expect(total).toBe(6 * 1024 * 1024);
});
it("emits 'drain' to resume a producer that paused on backpressure", async () => {
const app = express();
const order: string[] = [];
let routeFinished: () => void = () => {};
const routeDone = new Promise<void>((resolve) => { routeFinished = resolve; });
app.get("/bp2", async (_req, res) => {
res.setHeader("Content-Type", "application/octet-stream");
res.flushHeaders();
// Fill until backpressure. Capped so an implementation that never
// signals backpressure can't loop forever (it would just fail below).
let paused = false;
for (let i = 0; i < 64 && !paused; i++) {
paused = res.write(Buffer.alloc(1024 * 1024, i)) === false;
}
order.push(paused ? "paused" : "no-backpressure");
// Wait to be resumed, but never hang the suite if 'drain' never comes.
const outcome = await Promise.race([
once(res, "drain").then(() => "drained" as const),
new Promise<"timeout">((resolve) => setTimeout(() => resolve("timeout"), 3000))
]);
order.push(outcome);
res.end();
routeFinished();
});
const response = await dispatch(app, new Request("trilium-app://app/bp2"));
const body = response.body;
if (!body) throw new Error("expected a streaming body");
const reader = body.getReader();
// Draining the queue frees capacity, which pulls the stream and must emit
// 'drain' so the paused producer continues.
while (true) {
const { done } = await reader.read();
if (done) break;
}
await routeDone;
expect(order).toEqual(["paused", "drained"]);
});
it("returns a 500 Response when dispatch throws inside the protocol handler", async () => {
electronMock.handle.mockReset();
setupTriliumAppProtocol(express());
await Promise.resolve(); // let whenReady().then(...) run
expect(electronMock.handle).toHaveBeenCalledWith("trilium-app", expect.any(Function));
const handler = electronMock.handle.mock.calls[0][1] as (req: Request) => Promise<Response>;
// A malformed URL makes `new URL(request.url)` throw inside dispatch;
// the handler must convert that into a 500 rather than rejecting.
const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
const response = await handler({ url: "::::not-a-url", method: "GET", headers: new Headers(), signal: null } as unknown as Request);
errorSpy.mockRestore();
expect(response.status).toBe(500);
expect(await response.text()).toBe("Internal Server Error");
});
it("holds requests until a promised Express app resolves", async () => {
electronMock.handle.mockReset();
let resolveApp: (app: ReturnType<typeof buildTestApp>) => void = () => {};
setupTriliumAppProtocol(new Promise((res) => { resolveApp = res; }));
await Promise.resolve(); // let whenReady().then(...) run
const handler = electronMock.handle.mock.calls[0][1] as (req: Request) => Promise<Response>;
const responsePromise = handler(new Request("trilium-app://app/echo-json", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ hello: "world" })
}));
// The request must wait for the app instead of failing or settling early.
const settledEarly = await Promise.race([responsePromise.then(() => true), Promise.resolve(false)]);
expect(settledEarly).toBe(false);
resolveApp(buildTestApp());
const response = await responsePromise;
expect(response.status).toBe(200);
expect(await response.json()).toEqual({ echo: { hello: "world" } });
});
it("returns a 500 when the promised Express app rejects (server failed to start)", async () => {
electronMock.handle.mockReset();
let rejectApp: (err: Error) => void = () => {};
setupTriliumAppProtocol(new Promise((_res, rej) => { rejectApp = rej; }));
await Promise.resolve(); // let whenReady().then(...) run
const handler = electronMock.handle.mock.calls[0][1] as (req: Request) => Promise<Response>;
const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
const responsePromise = handler(new Request("trilium-app://app/anything"));
rejectApp(new Error("server never started"));
const response = await responsePromise;
errorSpy.mockRestore();
expect(response.status).toBe(500);
expect(await response.text()).toBe("Internal Server Error");
});
it("rejects when Express forwards an unhandled error to next()", async () => {
const app = express();
app.get("/boom", (_req, _res, next) => next(new Error("downstream failure")));
await expect(dispatch(app, new Request("trilium-app://app/boom"))).rejects.toThrow(/downstream failure/);
});
it("rejects (buffered path) when the response status is out of the Response range", async () => {
const app = express();
app.get("/bad", (_req, res) => {
res.statusCode = 999; // RangeError inside the Fetch Response constructor
res.end("x");
});
await expect(dispatch(app, new Request("trilium-app://app/bad"))).rejects.toThrow();
});
it("rejects (streaming path) when flushHeaders commits an out-of-range status", async () => {
const app = express();
app.get("/bad-stream", (_req, res) => {
res.statusCode = 999;
res.flushHeaders();
res.end();
});
await expect(dispatch(app, new Request("trilium-app://app/bad-stream"))).rejects.toThrow();
});
it("rejects when the Express app throws synchronously", async () => {
const app = () => { throw new Error("sync explosion"); };
await expect(dispatch(app as never, new Request("trilium-app://app/x"))).rejects.toThrow(/sync explosion/);
});
it("emits one header entry per value for multi-valued response headers", async () => {
const app = express();
app.get("/multi", (_req, res) => {
// Set-Cookie is the canonical header Express keeps as an array in getHeaders().
res.setHeader("Set-Cookie", ["a=1", "b=2"]);
res.send("ok");
});
const response = await dispatch(app, new Request("trilium-app://app/multi"));
expect(response.headers.getSetCookie()).toEqual(["a=1", "b=2"]);
});
it("passes binary buffer responses through untouched", async () => {
// Force the mock to expose a non-empty `_getBuffer` so the buffered
// branch picks the raw buffer rather than `_getData`.
type FakeRes = { statusCode: number; _getData: () => unknown; _getBuffer: () => Buffer; end: () => void };
const app = (_req: object, res: FakeRes) => {
res.statusCode = 200;
res._getData = () => "";
res._getBuffer = () => Buffer.from([1, 2, 3, 4]);
res.end();
};
const response = await dispatch(app as never, new Request("trilium-app://app/bin"));
expect(new Uint8Array(await response.arrayBuffer())).toEqual(new Uint8Array([1, 2, 3, 4]));
});
// The <audio>/<video> media data source refuses a response with no length, unlike
// fetch() which reads to EOF. Express's own Content-Length is stripped as a transport
// header (it can mismatch the buffered body), so the buffered path must restore one
// matching the exact bytes it emits — otherwise media playback fails over trilium-app://
// with MEDIA_ERR_SRC_NOT_SUPPORTED even though the same note plays over HTTP.
it("sets an accurate Content-Length on buffered responses (media playback)", async () => {
const app = express();
app.get("/media", (_req, res) => {
res.setHeader("Content-Type", "audio/mpeg");
res.send(Buffer.from([0, 1, 2, 3, 4]));
});
const response = await dispatch(app, new Request("trilium-app://app/media"));
expect(response.headers.get("content-length")).toBe("5");
expect(new Uint8Array(await response.arrayBuffer())).toEqual(new Uint8Array([0, 1, 2, 3, 4]));
});
it("does not set Content-Length on a null-body status response", async () => {
const app = express();
app.get("/nc", (_req, res) => res.status(204).send());
const response = await dispatch(app, new Request("trilium-app://app/nc"));
expect(response.headers.has("content-length")).toBe(false);
});
it("ignores a fetch abort that fires after a buffered response already completed", async () => {
const app = express();
app.get("/done", (_req, res) => res.send("done"));
const ac = new AbortController();
const response = await dispatch(app, new Request("trilium-app://app/done", { signal: ac.signal }));
expect(await response.text()).toBe("done");
// Late abort: the bridge's abort listener runs with streaming === false
// and must be a no-op.
ac.abort();
});
it("returns a null-body Response for null-body status codes", async () => {
const app = express();
app.get("/nc", (_req, res) => res.status(204).send());
const response = await dispatch(app, new Request("trilium-app://app/nc"));
expect(response.status).toBe(204);
expect(response.body).toBeNull();
});
it("drops hop-by-hop / transport headers from the response", async () => {
const app = express();
app.get("/stripped", (_req, res) => {
res.setHeader("Connection", "keep-alive");
res.send("ok");
});
const response = await dispatch(app, new Request("trilium-app://app/stripped"));
expect(response.headers.has("connection")).toBe(false);
});
it("wraps a non-Error value forwarded to next()", async () => {
const app = express();
app.get("/weird", (_req, _res, next) => next("string failure"));
await expect(dispatch(app, new Request("trilium-app://app/weird"))).rejects.toBeDefined();
});
it("returns an empty body when the buffered payload is null", async () => {
type FakeRes = { statusCode: number; _getData: () => unknown; _getBuffer: () => null; end: () => void };
const app = (_req: object, res: FakeRes) => {
res.statusCode = 200;
res._getData = () => null;
res._getBuffer = () => null;
res.end();
};
const response = await dispatch(app as never, new Request("trilium-app://app/empty"));
expect(await response.text()).toBe("");
});
it("falls back to _getData when the buffer is present but empty", async () => {
type FakeRes = { statusCode: number; _getData: () => unknown; _getBuffer: () => Buffer; end: () => void };
const app = (_req: object, res: FakeRes) => {
res.statusCode = 200;
res._getData = () => "from-data";
res._getBuffer = () => Buffer.alloc(0); // truthy buffer, zero length
res.end();
};
const response = await dispatch(app as never, new Request("trilium-app://app/emptybuf"));
expect(await response.text()).toBe("from-data");
});
it("tolerates upstream writes after a consumer abort tore the stream down", async () => {
const app = express();
let releaseTail: (() => void) | undefined;
const tail = new Promise<void>((r) => { releaseTail = r; });
app.get("/race", async (_req, res) => {
res.setHeader("Content-Type", "text/event-stream");
res.flushHeaders();
res.write("a\n");
await tail;
// After the abort below has nulled the controller, these must be
// inert no-ops rather than throwing.
res.write("b\n");
res.end();
});
const ac = new AbortController();
const response = await dispatch(app, new Request("trilium-app://app/race", { signal: ac.signal }));
const reader = response.body?.getReader();
if (!reader) throw new Error("expected a streaming body");
expect(new TextDecoder().decode((await reader.read()).value)).toBe("a\n");
ac.abort();
await expect(reader.read()).rejects.toThrow();
releaseTail?.();
await tail; // let the handler's post-abort writes run
});
it("survives the renderer cancelling the body stream mid-write, and tells the handler", async () => {
const app = express();
let releaseTail: (() => void) | undefined;
const tail = new Promise<void>((r) => { releaseTail = r; });
let writeError: unknown;
let closed = false;
app.get("/sse", async (_req, res) => {
res.setHeader("Content-Type", "text/event-stream");
res.flushHeaders();
// The disconnect signal llm_chat.ts uses to abort the agent turn.
res.on("close", () => { closed = true; });
res.write("a\n");
await tail;
try {
res.write("b\n");
res.end();
} catch (err) {
writeError = err;
}
});
// No AbortController: Electron's net layer cancels the response body
// when the renderer aborts, and that can land before the fetch signal.
const response = await dispatch(app, new Request("trilium-app://app/sse"));
const reader = response.body?.getReader();
if (!reader) throw new Error("expected a streaming body");
expect(new TextDecoder().decode((await reader.read()).value)).toBe("a\n");
await reader.cancel();
expect(closed).toBe(true);
releaseTail?.();
await tail;
expect(writeError).toBeUndefined();
});
it("signals 'close' once when the fetch abort tears the stream down", async () => {
const app = express();
let closeCount = 0;
app.get("/sse", (_req, res) => {
res.setHeader("Content-Type", "text/event-stream");
res.flushHeaders();
res.on("close", () => { closeCount++; });
res.write("a\n");
});
const ac = new AbortController();
const response = await dispatch(app, new Request("trilium-app://app/sse", { signal: ac.signal }));
const reader = response.body?.getReader();
if (!reader) throw new Error("expected a streaming body");
await reader.read();
ac.abort();
await expect(reader.read()).rejects.toThrow();
// The reader's own cancel path must not raise a second disconnect.
await reader.cancel().catch(() => {});
expect(closeCount).toBe(1);
});
it("serialises object and primitive response payloads to bytes", async () => {
// Express always stringifies objects/primitives before they reach the
// mock's buffer, so force the buffered branch to read a raw object /
// number out of `res._getData()` to exercise toUint8Array's fallbacks.
type FakeRes = { statusCode: number; _getData: () => unknown; _getBuffer: () => null; end: () => void };
const appReturning = (payload: unknown) => (_req: object, res: FakeRes) => {
res.statusCode = 200;
res._getData = () => payload;
res._getBuffer = () => null;
res.end();
};
const objResponse = await dispatch(appReturning({ hello: "world" }) as never, new Request("trilium-app://app/obj"));
expect(await objResponse.json()).toEqual({ hello: "world" });
const numResponse = await dispatch(appReturning(42) as never, new Request("trilium-app://app/num"));
expect(await numResponse.text()).toBe("42");
});
it("skips the request body for GET / HEAD and bodyless requests", async () => {
const app = express();
app.get("/get", (_req, res) => res.send("g"));
app.head("/head", (_req, res) => res.end());
expect(await (await dispatch(app, new Request("trilium-app://app/get"))).text()).toBe("g");
expect((await dispatch(app, new Request("trilium-app://app/head", { method: "HEAD" }))).status).toBe(200);
});
it("registerTriliumAppScheme declares the privileged custom scheme", () => {
registerTriliumAppScheme();
expect(electronMock.registerSchemesAsPrivileged).toHaveBeenCalledWith([
expect.objectContaining({
scheme: "trilium-app",
privileges: expect.objectContaining({ standard: true, secure: true, supportFetchAPI: true, corsEnabled: true, codeCache: true })
})
]);
});
// Every dispatched request gets the auth/CSRF-bypassing internal marker,
// so requests must be vetted before they ever reach `dispatch`. The
// primary gate is the webRequest frame-origin guard (headers cannot
// distinguish friend from foe on a custom scheme — see protocol.ts);
// the Origin check on the handler itself is the secondary layer for
// navigation-style requests, the only ones that carry an Origin.
describe("origin gate", () => {
async function installHandler(app: Parameters<typeof setupTriliumAppProtocol>[0]) {
electronMock.handle.mockReset();
setupTriliumAppProtocol(app);
await Promise.resolve(); // let whenReady().then(...) run
return electronMock.handle.mock.calls[0][1] as (req: Request) => Promise<Response>;
}
// Real `Request` objects can't be used here: undici may strip the
// forbidden `Origin` header, while Chromium's protocol handler hands
// us requests that DO carry it. A plain Headers-backed shape models
// the production input deterministically.
function fakeRequest(method: string, origin?: string): Request {
return {
method,
url: "trilium-app://app/probe",
headers: new Headers(origin === undefined ? {} : { origin }),
signal: null,
body: null
} as unknown as Request;
}
it("isDispatchOriginAllowed only rejects positively-attested foreign origins", () => {
// Foreign origins are rejected, including the opaque "null"
// origin of sandboxed frames and other hosts under our own
// scheme — `trilium-app://app` is the only origin the app ever
// loads.
expect(isDispatchOriginAllowed("https://evil.example")).toBe(false);
expect(isDispatchOriginAllowed("null")).toBe(false);
expect(isDispatchOriginAllowed("trilium-app://evil")).toBe(false);
expect(isDispatchOriginAllowed("trilium-app://app.evil.example")).toBe(false);
// The app's own exact origin passes.
expect(isDispatchOriginAllowed("trilium-app://app")).toBe(true);
// No Origin proves nothing on a custom scheme: Chromium omits it
// even on the renderer's own POST/PUT requests, so absence must
// be allowed through (the frame guard already vetted the source).
expect(isDispatchOriginAllowed(null)).toBe(true);
});
it("returns 403 without invoking the Express app for a foreign-origin request", async () => {
let appInvoked = false;
const app = express();
app.post("/probe", (_req, res) => {
appInvoked = true;
res.send("ok");
});
const handler = await installHandler(app);
const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
const response = await handler(fakeRequest("POST", "https://evil.example"));
errorSpy.mockRestore();
expect(response.status).toBe(403);
expect(appInvoked).toBe(false);
});
// Regression test: same-origin renderer writes (tree/load,
// recent-notes, ...) arrive with NO Origin header on the custom
// scheme and must not be rejected.
it("dispatches Origin-less writes (the renderer's own API calls)", async () => {
const app = express();
app.post("/probe", (_req, res) => res.send("written"));
const handler = await installHandler(app);
const response = await handler(fakeRequest("POST"));
expect(response.status).toBe(200);
expect(await response.text()).toBe("written");
});
it("dispatches writes carrying the exact trilium-app Origin", async () => {
const app = express();
app.post("/probe", (_req, res) => res.send("written"));
const handler = await installHandler(app);
const response = await handler(fakeRequest("POST", "trilium-app://app"));
expect(response.status).toBe(200);
expect(await response.text()).toBe("written");
});
it("dispatches Origin-less GETs (top-level navigation path)", async () => {
const app = express();
app.get("/probe", (_req, res) => res.send("page"));
const handler = await installHandler(app);
const response = await handler(fakeRequest("GET"));
expect(response.status).toBe(200);
expect(await response.text()).toBe("page");
});
});
// The primary gate: a webRequest hook cancels any trilium-app:// request
// whose requesting frame chain is not exclusively the app shell. Frame
// URLs are main-process-side state that renderer content cannot forge,
// unlike every header on this scheme.
describe("frame origin guard", () => {
type OnBeforeRequestListener = (
details: {
method: string;
url: string;
resourceType: string;
frame?: { url: string; parent: unknown } | null;
},
callback: (response: { cancel: boolean }) => void
) => void;
async function installGuard() {
electronMock.onBeforeRequest.mockReset();
setupTriliumAppProtocol(express());
await Promise.resolve(); // let whenReady().then(...) run
const [filter, listener] = electronMock.onBeforeRequest.mock.calls[0] as [
{ urls: string[] },
OnBeforeRequestListener
];
return { filter, listener };
}
function frameChain(...urls: string[]) {
return urls.reduceRight<{ url: string; parent: unknown } | null>(
(parent, url) => ({ url, parent }),
null
);
}
function decide(listener: OnBeforeRequestListener, resourceType: string, frame: { url: string; parent: unknown } | null | undefined) {
let cancelled: boolean | undefined;
const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
listener(
{ method: "POST", url: "trilium-app://app/api/probe", resourceType, frame },
({ cancel }) => { cancelled = cancel; }
);
errorSpy.mockRestore();
return cancelled;
}
it("isRequestorChainTrusted implements the frame-chain policy", () => {
// Top-level navigations come from main-process loadURL calls or
// are vetted by the will-navigate guard — always allowed.
expect(isRequestorChainTrusted("mainFrame", [""])).toBe(true);
// The renderer's own fetch/XHR.
expect(isRequestorChainTrusted("xhr", ["trilium-app://app/"])).toBe(true);
// ... including from same-origin iframes (pdfjs viewer, print).
expect(isRequestorChainTrusted("xhr", ["trilium-app://app/pdfjs/web/viewer.html", "trilium-app://app/"])).toBe(true);
// Subframe navigation of a legit app iframe: the navigated frame
// reports its uncommitted URL; the app-shell parent attests it.
expect(isRequestorChainTrusted("subFrame", ["", "trilium-app://app/"])).toBe(true);
expect(isRequestorChainTrusted("subFrame", ["about:blank", "trilium-app://app/"])).toBe(true);
// DevTools fetching source maps for trilium-app:// scripts.
expect(isRequestorChainTrusted("xhr", ["devtools://devtools/bundled/devtools_app.html"])).toBe(true);
// A foreign window's fetch.
expect(isRequestorChainTrusted("xhr", ["http://127.0.0.1:8080/"])).toBe(false);
// A foreign iframe embedded in the app window — the app-shell
// ancestor does not launder the hostile requesting frame.
expect(isRequestorChainTrusted("xhr", ["http://evil.example/", "trilium-app://app/"])).toBe(false);
// A hostile form POST targeting an iframe, from a foreign window
// or nested inside the app window.
expect(isRequestorChainTrusted("subFrame", ["about:blank", "http://evil.example/"])).toBe(false);
expect(isRequestorChainTrusted("subFrame", ["about:blank", "http://evil.example/", "trilium-app://app/"])).toBe(false);
// Lookalike hosts under our own or other schemes.
expect(isRequestorChainTrusted("xhr", ["trilium-app://app.evil.example/"])).toBe(false);
expect(isRequestorChainTrusted("xhr", ["trilium-app://evil/"])).toBe(false);
// Chains with no committed frame at all attest nothing.
expect(isRequestorChainTrusted("xhr", ["about:blank"])).toBe(false);
expect(isRequestorChainTrusted("xhr", [])).toBe(false);
// Unparseable frame URLs.
expect(isRequestorChainTrusted("xhr", ["<disposed frame>"])).toBe(false);
});
it("registers for trilium-app URLs and cancels based on the frame chain", async () => {
const { filter, listener } = await installGuard();
expect(filter).toEqual({ urls: ["trilium-app://*/*"] });
expect(decide(listener, "xhr", frameChain("trilium-app://app/"))).toBe(false);
expect(decide(listener, "xhr", frameChain("http://evil.example/", "trilium-app://app/"))).toBe(true);
expect(decide(listener, "mainFrame", frameChain(""))).toBe(false);
});
it("denies subresource requests with no frame attached", async () => {
const { listener } = await installGuard();
expect(decide(listener, "xhr", null)).toBe(true);
expect(decide(listener, "xhr", undefined)).toBe(true);
});
it("denies when reading the frame chain throws (disposed frame)", async () => {
const { listener } = await installGuard();
const disposed = {
get url(): string { throw new Error("Render frame was disposed"); },
parent: null
};
expect(decide(listener, "xhr", disposed)).toBe(true);
});
});
it("does NOT tag plain Express requests with the internal-electron marker", () => {
// Anything that didn't come through `dispatch()` — i.e. a real HTTP
// request to the TCP listener, or an arbitrary attacker-controlled
// payload — must register as untagged.
const plainReq = {} as object;
expect(isInternalElectronRequest(plainReq)).toBe(false);
// An attacker can't forge the marker via HTTP headers / body fields
// because the marker is keyed by a non-exported Symbol. Header maps
// and JSON-decoded bodies that mention the string "trilium-electron-
// internal-request" can't reach the Symbol-keyed slot.
const headerForgery = { headers: { "trilium-electron-internal-request": "true" } };
const bodyForgery = { body: { "trilium-electron-internal-request": true } };
const stringKeyForgery: Record<string, unknown> = { "trilium-electron-internal-request": true };
expect(isInternalElectronRequest(headerForgery)).toBe(false);
expect(isInternalElectronRequest(bodyForgery)).toBe(false);
expect(isInternalElectronRequest(stringKeyForgery)).toBe(false);
});
});