Skip to content

~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.

21.4 KB
Raw Blame
/**
 * API Service
 * Handles all communication with the server API endpoints
 * Note: URLValidator is available globally via /static/js/security/url-validator.js
 */

// Base URL for API - guard against duplicate script loading (same pattern as urls.js)
// Uses window property to survive duplicate <script> loads without redeclaring.
const API_BASE_URL = (typeof window !== 'undefined' && typeof window.API_BASE_URL !== 'undefined')
    ? window.API_BASE_URL
    : '/api';

/**
 * Get CSRF token from meta tag
 * @returns {string} The CSRF token
 */
function getCsrfToken() {
    const metaTag = document.querySelector('meta[name="csrf-token"]');
    return metaTag ? metaTag.getAttribute('content') : '';
}

/** Read the non-authenticating fingerprint of the login that rendered this page. */
function getAuthContext() {
    const value = document.querySelector('meta[name="auth-context"]')?.getAttribute('content');
    return typeof value === 'string' && /^[a-f0-9]{64}$/.test(value) ? value : null;
}

/** Retry only a rejected CSRF check, once, within the page's original login. */
async function fetchWithCsrfRecovery(url, options = {}, send = fetch) {
    const method = (options.method || 'GET').toUpperCase();
    const repeatableBody = options.body == null || typeof options.body === 'string';
    let internal = false;
    if (typeof url === 'string' && url.startsWith('/') && typeof window !== 'undefined' && window.location?.href) {
        const target = new URL(url, window.location.href);
        internal = target.origin === new URL(window.location.href).origin
            && !target.pathname.startsWith('/auth/')
            && !window.location.pathname.startsWith('/auth/');
    }
    const eligible = internal && ['POST', 'PUT', 'PATCH', 'DELETE'].includes(method)
        && repeatableBody && options.credentials !== 'omit';
    const context = eligible ? getAuthContext() : null;
    // Snapshot the headers before sending. Do not mutate a caller's Headers
    // instance or let later changes replace the original request's context.
    let initialOptions = options;
    if (context) {
        const headers = new globalThis.Headers(options.headers);
        headers.set('X-LDR-Auth-Context', context);
        initialOptions = { ...options, headers };
    }
    const response = await send(url, initialOptions);
    if (!context || response.status !== 403 || response.redirected
        || response.headers?.get('X-LDR-CSRF-Rejected') !== '1') {
        return response;
    }

    // The marker is emitted only by middleware before a handler is entered.
    // Streams/uploads are never replayed, nor are ordinary application 403s.
    options.signal?.throwIfAborted();
    const refresh = await send('/auth/csrf-token', {
        method: 'GET', credentials: 'same-origin', cache: 'no-store', redirect: 'error',
        headers: { 'X-LDR-Auth-Context': context }, signal: options.signal
    });
    options.signal?.throwIfAborted();
    if (getAuthContext() !== context) {
        throw new Error('Your sign-in changed. Reload this page before trying again.');
    }
    // The refresh returns 401/409 if the login expired or was replaced, or
    // 503 if the session cannot be checked right now (it is kept). Let the
    // existing auth/error handling surface it; no original write is sent.
    if (!refresh.ok) return refresh;
    const fresh = await refresh.json();
    options.signal?.throwIfAborted();
    if (typeof fresh?.auth_context !== 'string' || typeof fresh?.csrf_token !== 'string' || !fresh.csrf_token) {
        return response;
    }
    if (fresh.auth_context !== context || getAuthContext() !== context) {
        throw new Error('Your sign-in changed. Reload this page before trying again.');
    }
    document.querySelector('meta[name="csrf-token"]')?.setAttribute('content', fresh.csrf_token);
    const headers = new globalThis.Headers(initialOptions.headers);
    headers.delete('X-CSRF-Token');
    headers.set('X-CSRFToken', fresh.csrf_token);
    // A direct send (not recursion) caps the entire operation at one retry.
    // Reuse the original signal so refresh does not reset its timeout.
    return send(url, { ...initialOptions, headers });
}

/**
 * True when the server refused a request because this page's login was
 * replaced (e.g. the user signed in again in another tab). CSRFMiddleware and
 * /auth/csrf-token mark that 409 with X-LDR-Auth-Changed: 1; an endpoint's own
 * 409 (such as "indexing already running") never carries it. The body's
 * `error` holds the message to show; do not match on its prose.
 *
 * @param {Response} response
 * @returns {boolean}
 */
function isAuthContextChanged(response) {
    return response?.status === 409
        && response.headers?.get?.('X-LDR-Auth-Changed') === '1';
}

/**
 * Get the full URL for an API endpoint
 * @param {string} path - The API path (without leading slash)
 * @returns {string} The full API URL
 */
function getApiUrl(path) {
    return `${API_BASE_URL}/${path}`;
}

/**
 * Decide whether a 401 from `url` should bounce the user to the login page.
 *
 * Only same-origin (leading-slash) API URLs qualify: a 401 from a third-party
 * URL means that API rejected us, not that our own session expired. We also
 * never redirect while already inside the /auth/* flow (that would loop), and
 * we leave requests to /auth/* itself alone (the auth subsystem handles its
 * own 401 states, e.g. failed login validation).
 *
 * @param {string} url - The request URL
 * @returns {boolean}
 */
function shouldRedirectToLoginOn401(url) {
    if (typeof window === 'undefined') return false;
    if (!url.startsWith('/')) return false;                          // external (absolute) URL
    // Reject cross-origin bypass forms: //host is protocol-relative, and a
    // backslash is normalized to '/' by browsers, so both //host and /\host
    // resolve cross-origin (verified via URL()). Mirrors the server's
    // is_safe_redirect_url, which rejects a leading // and any backslash.
    if (url.startsWith('//') || url.includes('\\')) return false;
    if (window.location.pathname.startsWith('/auth/')) return false; // already in login flow
    if (url.startsWith('/auth/')) return false;                      // auth handles its own 401s
    return true;
}

/**
 * Send the user to the login page, preserving the current location as `next`
 * so they land back where they were after re-authenticating.
 *
 * `next` is a same-origin relative path (pathname + query + hash): staying
 * relative means it's trivially same-origin, and keeping the hash preserves
 * in-page state (e.g. #logs) so the user lands exactly where they were. The
 * server re-validates it via URLValidator.get_safe_redirect_path anyway.
 */
function redirectToLogin() {
    const next = encodeURIComponent(
        window.location.pathname + window.location.search + window.location.hash
    );
    // Hardcoded /auth/login target; `next` is a same-origin relative path that
    // the server re-validates (get_safe_redirect_path) before redirecting.
    // bearer:disable javascript_lang_open_redirect
    window.location.href = `/auth/login?next=${next}`;
}

/** Recover a stale logout form without applying it to a replacement login. */
async function submitLogout(form) {
    if (form.dataset.logoutPending === 'true') return;
    form.dataset.logoutPending = 'true';
    form.setAttribute('aria-busy', 'true');
    // The control is a link (see base.html), so mark it busy rather than
    // relying on `disabled`; logoutPending above already blocks re-entry.
    const control = form.querySelector('.ldr-logout-btn');
    if (control) control.setAttribute('aria-disabled', 'true');
    const controller = new AbortController();
    const timeout = setTimeout(() => controller.abort(), 30000);
    const changed = 'Your sign-in changed. Reload this page before logging out.';

    try {
        const context = getAuthContext();
        if (!context) throw new Error('Reload this page before logging out.');
        const options = {
            credentials: 'same-origin', cache: 'no-store', redirect: 'error',
            signal: controller.signal,
            headers: { 'Accept': 'application/json', 'X-LDR-Auth-Context': context }
        };
        const refresh = await fetch('/auth/csrf-token', { ...options, method: 'GET' });
        if (getAuthContext() !== context || refresh.status === 409) throw new Error(changed);
        if (refresh.status === 401) {
            window.location.href = '/auth/login';
            return;
        }
        if (!refresh.ok) throw new Error('Could not check your session. Please try logging out again.');
        const fresh = await refresh.json();
        if (getAuthContext() !== context || fresh.auth_context !== context) throw new Error(changed);
        if (typeof fresh.csrf_token !== 'string' || !fresh.csrf_token) {
            throw new Error('Could not refresh your session. Reload this page before logging out.');
        }
        // Not signal.throwIfAborted(): it needs Safari 15.4 / Chrome 100 /
        // Firefox 97, and its absence would block logout on older browsers.
        if (controller.signal.aborted) throw new window.DOMException('Aborted', 'AbortError');
        const response = await fetch('/auth/logout', {
            ...options, method: 'POST',
            headers: { ...options.headers, 'X-CSRFToken': fresh.csrf_token }
        });
        if (getAuthContext() !== context || response.status === 409) throw new Error(changed);
        if (response.status === 401) {
            window.location.href = '/auth/login';
            return;
        }
        if (!response.ok) throw new Error('Could not log out. Reload this page and try again.');
        const result = await response.json();
        if (getAuthContext() !== context) throw new Error(changed);
        if (result.success !== true) throw new Error('Logout was not confirmed. Please try again.');
        window.location.href = '/auth/login';
    } catch (error) {
        // A transport failure may happen after logout succeeded. Leave a
        // retry to the user; its fresh session check handles that case.
        const message = error.name === 'AbortError'
            ? 'Logout timed out. Please try again.'
            : error instanceof TypeError
                ? 'Could not confirm logout. Please check your connection and try again.'
                : error.message;
        window.ui.showMessage(message, 'error', 10000);
    } finally {
        clearTimeout(timeout);
        delete form.dataset.logoutPending;
        form.removeAttribute('aria-busy');
        if (control) control.removeAttribute('aria-disabled');
    }
}

/**
 * Generic fetch with error handling and timeout support
 * @param {string} url - The URL to fetch
 * @param {Object} options - Fetch options
 * @param {number} [options.timeout=30000] - Request timeout in milliseconds (default: 30s)
 * @returns {Promise<any>} The parsed response data
 */
async function fetchWithErrorHandling(url, options = {}) {
    const {
        timeout = 30000,
        signal: callerSignal,
        ...fetchOptions
    } = options;
    const controller = new AbortController();
    let abortCause = null;
    const abortFromCaller = () => {
        if (controller.signal.aborted) return;
        abortCause = 'caller';
        controller.abort(callerSignal?.reason);
    };
    if (callerSignal) {
        if (callerSignal.aborted) {
            abortFromCaller();
        } else {
            callerSignal.addEventListener('abort', abortFromCaller, { once: true });
        }
    }
    const timeoutId = setTimeout(() => {
        if (controller.signal.aborted) return;
        abortCause = 'timeout';
        controller.abort();
    }, timeout);

    try {
        const csrfToken = getCsrfToken();
        // This wrapper parses JSON even for routes outside /api/. Advertise
        // that response type so an expired session produces a JSON 401.
        const headers = new globalThis.Headers({
            'Accept': 'application/json',
            'Content-Type': 'application/json',
            ...(csrfToken ? { 'X-CSRFToken': csrfToken } : {})
        });
        new globalThis.Headers(fetchOptions.headers ?? {}).forEach((value, name) => {
            headers.set(name, value);
        });
        const response = await fetchWithCsrfRecovery(url, {
            ...fetchOptions,
            signal: controller.signal,
            headers
        });

        // Expired/invalid session on an internal API call: bounce the user to
        // login (preserving where they were) instead of throwing an opaque
        // "API Error: 401" that every caller would have to special-case. The
        // returned Promise never resolves because the page is navigating away.
        if (response.status === 401 && shouldRedirectToLoginOn401(url)) {
            redirectToLogin();
            return new Promise(() => {});
        }

        // Handle non-200 responses.
        // FastAPI's HTTPException puts the message under `detail`, not
        // `error` or `message` — without checking `detail` first, every
        // 401/403/404 surfaced as the generic "API Error: 401..." and
        // the UI lost session-expired / CSRF-missing messages.
        if (!response.ok) {
            const errorData = await response.json().catch(() => ({}));
            const error = new Error(
                errorData?.message ||
                errorData?.error ||
                errorData?.detail ||
                `API Error: ${response.status} ${response.statusText}`
            );
            // Preserve the parsed error body so callers can surface
            // structured details the single-message throw discards — e.g.
            // the per-setting `errors` array the settings save routes
            // return alongside the generic "Validation errors" message.
            // Only a non-empty object body has anything worth forwarding:
            // null bodies and unparseable payloads resolve to nothing.
            if (
                errorData &&
                typeof errorData === 'object' &&
                Object.keys(errorData).length > 0
            ) {
                error.details = errorData;
            }
            throw error;
        }

        // Parse the response
        return await response.json();
    } catch (error) {
        if (error.name === 'AbortError') {
            if (abortCause === 'timeout') {
                throw new Error('Request timed out');
            }
            // Caller-owned cancellation is expected control flow (for
            // example, a newer request superseding an older one). Preserve
            // the original AbortError without reporting it as an API failure.
            if (abortCause === 'caller') {
                throw error;
            }
        }
        SafeLogger.error('API Error:', error);
        throw error;
    } finally {
        clearTimeout(timeoutId);
        callerSignal?.removeEventListener('abort', abortFromCaller);
    }
}

/**
 * Helper method to perform POST requests with JSON data
 * @param {string} path - API path
 * @param {Object} data - JSON data to send
 * @returns {Promise<any>} Response data
 */
async function postJSON(path, data) {
    return fetchWithErrorHandling(path, {
        method: 'POST',
        body: JSON.stringify(data)
    });
}

/**
 * Start a new research
 * @param {string} query - The research query
 * @param {string} mode - The research mode (quick/detailed)
 * @returns {Promise<Object>} The research response with ID
 */
async function startResearch(query, mode) {
    return postJSON(URLS.API.START_RESEARCH, { query, mode });
}

/**
 * Get a research status by ID
 * @param {number} researchId - The research ID
 * @returns {Promise<Object>} The research status
 */
async function getResearchStatus(researchId) {
    return fetchWithErrorHandling(URLBuilder.researchStatus(researchId));
}

/**
 * Get research details
 * @param {number} researchId - The research ID
 * @returns {Promise<Object>} The research details
 */
async function getResearchDetails(researchId) {
    return fetchWithErrorHandling(URLBuilder.researchDetails(researchId));
}

/**
 * Get research logs
 * @param {number} researchId - The research ID
 * @returns {Promise<Object>} The research logs
 */
async function getResearchLogs(researchId) {
    return fetchWithErrorHandling(URLBuilder.researchLogs(researchId));
}

/**
 * Get research history
 * @returns {Promise<Array>} The research history
 */
async function getResearchHistory() {
    return fetchWithErrorHandling(URLS.API.HISTORY);
}

/**
 * Get research report
 * @param {number} researchId - The research ID
 * @returns {Promise<Object>} The research report
 */
async function getReport(researchId) {
    return fetchWithErrorHandling(URLBuilder.researchReport(researchId));
}

/**
 * Terminate a research
 * @param {number} researchId - The research ID
 * @returns {Promise<Object>} The termination response
 */
async function terminateResearch(researchId) {
    return postJSON(URLBuilder.terminateResearch(researchId), {});
}

/**
 * Delete a research
 * @param {number} researchId - The research ID
 * @returns {Promise<Object>} The deletion response
 */
async function deleteResearch(researchId) {
    return fetchWithErrorHandling(URLBuilder.deleteResearch(researchId), {
        method: 'DELETE'
    });
}

/**
 * Clear all research history
 * @returns {Promise<Object>} The response
 */
async function clearResearchHistory() {
    return postJSON(URLS.API.CLEAR_HISTORY, {});
}

/**
 * Open a file location in the system file explorer
 * @param {string} path - Path to open
 * @returns {Promise<Object>} The response
 */
async function openFileLocation(path) {
    return postJSON('/settings/open_file_location', { path });
}

/**
 * Save raw configuration
 * @param {string} rawConfig - Raw configuration text
 * @returns {Promise<Object>} The response
 */
async function saveRawConfig(rawConfig) {
    return postJSON(URLS.API.SAVE_RAW_CONFIG, { raw_config: rawConfig });
}

/**
 * Save main configuration
 * @param {Object} config - Configuration object
 * @returns {Promise<Object>} The response
 */
async function saveMainConfig(config) {
    return postJSON(URLS.API.SAVE_MAIN_CONFIG, config);
}

/**
 * Save search engines configuration
 * @param {Object} config - Configuration object
 * @returns {Promise<Object>} The response
 */
async function saveSearchEnginesConfig(config) {
    return postJSON(URLS.API.SAVE_SEARCH_ENGINES_CONFIG, config);
}

/**
 * Save collections configuration
 * @param {Object} config - Configuration object
 * @returns {Promise<Object>} The response
 */
async function saveCollectionsConfig(config) {
    return postJSON(URLS.API.SAVE_COLLECTIONS_CONFIG, config);
}

/**
 * Save API keys configuration
 * @param {Object} config - Configuration object
 * @returns {Promise<Object>} The response
 */
async function saveApiKeysConfig(config) {
    return postJSON(URLS.API.SAVE_API_KEYS_CONFIG, config);
}

/**
 * Save LLM configuration
 * @param {Object} config - Configuration object
 * @returns {Promise<Object>} The response
 */
async function saveLlmConfig(config) {
    return postJSON(URLS.API.SAVE_LLM_CONFIG, config);
}

/**
 * Get markdown export for research
 * @param {number} researchId - The research ID
 * @returns {Promise<Object>} The markdown content
 */
async function getMarkdownExport(researchId) {
    return fetchWithErrorHandling(URLBuilder.markdownExport(researchId));
}

// Export for Node.js testing
if (typeof module !== 'undefined' && module.exports) {
    module.exports = {
        getCsrfToken,
        fetchWithErrorHandling,
        fetchWithCsrfRecovery,
        shouldRedirectToLoginOn401,
        redirectToLogin,
        getApiUrl,
        postJSON,
        startResearch,
        getResearchStatus,
        getResearchDetails,
        getResearchLogs,
        getResearchHistory,
        getReport,
        getMarkdownExport,
        terminateResearch,
        deleteResearch,
        clearResearchHistory,
        openFileLocation,
        saveRawConfig,
        saveMainConfig,
        saveSearchEnginesConfig,
        saveCollectionsConfig,
        saveApiKeysConfig,
        saveLlmConfig
    };
}

// Make api available globally for browser usage
if (typeof window !== 'undefined') {
    document.addEventListener('submit', async event => {
        if (event.target.id !== 'logout-form') return;
        event.preventDefault();
        await submitLogout(event.target);
    });
    // The top-bar logout control is a link rather than a submit button
    // (base.html), so page-wide submit-button selectors never match it.
    document.addEventListener('click', async event => {
        const control = event.target instanceof Element
            ? event.target.closest('#logout-form .ldr-logout-btn')
            : null;
        if (!control) return;
        event.preventDefault();
        await submitLogout(control.closest('form'));
    });
    window.api = {
        startResearch,
        getResearchStatus,
        getResearchDetails,
        getResearchLogs,
        getResearchHistory,
        getReport,
        getMarkdownExport,
        terminateResearch,
        deleteResearch,
        clearResearchHistory,
        openFileLocation,
        saveRawConfig,
        saveMainConfig,
        saveSearchEnginesConfig,
        saveCollectionsConfig,
        saveApiKeysConfig,
        saveLlmConfig,
        postJSON,
        getApiUrl,
        getCsrfToken,
        fetchWithErrorHandling,
        fetchWithCsrfRecovery,
        isAuthContextChanged,
        // Exposed so the direct-safeFetch call sites (library/settings/etc.)
        // can adopt the same 401->login behavior without duplicating the logic.
        shouldRedirectToLoginOn401,
        redirectToLogin
    };
}