Skip to content

Build your personal knowledge base with Trilium Notes

8.3 KB
Raw Blame
import { ValidationError } from "../errors.js";

export interface CookieJar {
    header?: string;
}

export interface ExecOpts {
    proxy: string | null;
    method: string;
    url: string;
    paging?: {
        pageCount: number;
        pageIndex: number;
        requestId: string;
    };
    cookieJar?: CookieJar;
    auth?: {
        password?: string;
        /** Sent as `trilium-totp` when the server has two-factor authentication enabled. */
        totpToken?: string;
    };
    timeout: number;
    body?: string | {};
}

/** What a resource fetch is allowed to cost, and what it asks for. */
export interface FetchResourceOpts {
    /**
     * Refuse a body larger than this — both up front, where the server advertises a size, and while
     * it streams, where it does not.
     *
     * Required rather than defaulted, because the ceiling is the whole point: what arrives is a
     * third party's answer, held whole in memory, and on the runtime where that memory is a browser
     * tab there is no second line of defence behind it.
     */
    maxBytes: number;
    headers?: Record<string, string>;
}

/** A resource that arrived whole, within its ceiling. */
export interface FetchedResource {
    status: number;
    ok: boolean;
    /** The media type alone, parameters stripped; empty where the server named none. */
    contentType: string;
    bytes: Uint8Array;
}

export interface RequestProvider {
    exec<T>(opts: ExecOpts): Promise<T>;
    getImage(imageUrl: string): Promise<ArrayBuffer>;
    /**
     * Fetches a third-party resource named by note content or by the user, capped at
     * {@link FetchResourceOpts.maxBytes}.
     *
     * Distinct from {@link getImage} in the two things a caller reading a page needs and a caller
     * downloading a picture never did: a ceiling on what it will hold, and the media type it came
     * under. Distinct from {@link exec} in that it is neither JSON nor Trilium's own protocol — the
     * body is handed back as bytes, and what they mean is the caller's business.
     *
     * Throws rather than answering when the resource cannot be had at all: the URL is refused, the
     * transport fails, or the body exceeds its ceiling. A non-2xx *answer* is not that — it comes
     * back with its status, since a caller may well want to read an error page's content type.
     *
     * How hard the address is vetted is the implementation's to decide, and differs by runtime by
     * necessity — see the note on each.
     */
    fetchResource(url: string, opts: FetchResourceOpts): Promise<FetchedResource>;
    /**
     * Calls an API endpoint whose address came from configuration — the LLM providers' base URL
     * being the one that exists today — and hands back the response still open.
     *
     * Distinct from {@link fetchResource} in the two things calling an API needs and reading a page
     * never did: a request of one's own, with a method and headers and a body, and an answer nobody
     * buffers. A completion streams for as long as the model takes, so there is no ceiling to put on
     * it and nothing here may hold it whole.
     *
     * The address still has to be vetted — a base URL is a free-text field, and a server that
     * fetches whatever it is pointed at is a server that will fetch a cloud metadata endpoint. How
     * hard, and against which ranges, is the implementation's to decide; see the note on each.
     */
    fetchApi(url: string, init: RequestInit, opts: FetchApiOpts): Promise<Response>;
}

/** What an API call needs vetting for, beyond the address itself. */
export interface FetchApiOpts {
    /**
     * Whether the destination may sit on a private network. True for an endpoint the operator
     * configured — a model server on this machine or this LAN is the ordinary case, and refusing
     * it would leave the local providers with nothing to talk to. Never true for an address that
     * arrived in note content.
     */
    allowPrivateNetwork: boolean;
}

let requestProvider: RequestProvider | null = null;

export function initRequest(provider: RequestProvider): void {
    requestProvider = provider;
}

export function getRequestProvider(): RequestProvider {
    if (!requestProvider) {
        throw new Error("Request provider not initialized. Call initRequest() first.");
    }
    return requestProvider;
}

export function isRequestInitialized(): boolean {
    return requestProvider !== null;
}

export default {
    exec<T>(opts: ExecOpts): Promise<T> {
        return getRequestProvider().exec(opts);
    },
    getImage(imageUrl: string): Promise<ArrayBuffer> {
        return getRequestProvider().getImage(imageUrl);
    },
    fetchResource(url: string, opts: FetchResourceOpts): Promise<FetchedResource> {
        return getRequestProvider().fetchResource(url, opts);
    },
    fetchApi(url: string, init: RequestInit, opts: FetchApiOpts): Promise<Response> {
        return getRequestProvider().fetchApi(url, init, opts);
    }
};

/**
 * The checks on an outbound address that hold on every runtime, being about the address itself
 * rather than about what it resolves to.
 *
 * Resolving the name and refusing the private addresses behind it is the other half of this, and it
 * cannot live here: it needs a resolver, which is a Node module on one runtime and does not exist
 * at all on another. So an implementation that has one does that too — see the server's safeFetch —
 * and one that does not still gets these, which are the checks that need no network to make.
 */
export function validateFetchableUrl(urlString: string): URL {
    let parsed: URL;
    try {
        parsed = new URL(urlString);
    } catch {
        throw new ValidationError("Invalid URL");
    }

    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
        throw new ValidationError("Only http and https URLs are supported");
    }

    // `https://user:pass@host/` would put the credentials on the wire, and — for a link preview —
    // into the note's stored URL and the log along with them. Nothing here needs to authenticate,
    // so refuse the URL rather than carry a secret around.
    if (parsed.username || parsed.password) {
        throw new ValidationError("URLs containing credentials are not supported");
    }

    return parsed;
}

/**
 * Reads a `Response` into a {@link FetchedResource}, refusing a body over `maxBytes`.
 *
 * Shared by every implementation that has a real `Response` to read — the server's, which gets one
 * from its SSRF-hardened fetch, and the browser's, which gets one from `fetch` itself. Only the
 * getting of it differs between those two; the counting does not, and counting is the part with the
 * edge cases: a size advertised and a size not, a body that lies about the first, a stream that has
 * to be abandoned mid-flight rather than read to the end just to discover it was too long.
 */
export async function readCappedResponse(response: Response, maxBytes: number): Promise<FetchedResource> {
    const contentType = (response.headers.get("content-type") ?? "").split(";")[0].trim().toLowerCase();
    const base = { status: response.status, ok: response.ok, contentType };

    // Bail before reading a byte where the server says how many there will be.
    const advertised = response.headers.get("content-length");
    if (advertised && Number(advertised) > maxBytes) {
        void response.body?.cancel();
        throw new Error(`Response of ${advertised} bytes exceeds the ${maxBytes} byte limit`);
    }

    const reader = response.body?.getReader();
    if (!reader) {
        return { ...base, bytes: new Uint8Array() };
    }

    const chunks: Uint8Array[] = [];
    let total = 0;

    for (;;) {
        const { done, value } = await reader.read();
        if (done) break;

        total += value.byteLength;

        // Checked as it streams, because content-length is a claim and a chunked response makes no
        // claim at all. Abandoned at the moment it goes over rather than read to the end.
        if (total > maxBytes) {
            void reader.cancel();
            throw new Error(`Response exceeds the ${maxBytes} byte limit`);
        }

        chunks.push(value);
    }

    const bytes = new Uint8Array(total);
    let offset = 0;
    for (const chunk of chunks) {
        bytes.set(chunk, offset);
        offset += chunk.byteLength;
    }

    return { ...base, bytes };
}