Skip to content

Build your personal knowledge base with Trilium Notes

10.6 KB
Raw Blame
/**
 * REST endpoints for the OneNote importer. Implements the OAuth device authorization grant (delegated
 * Microsoft Graph access) and the actual import. Tokens live in the user's session only — they are
 * never written to the synced options store.
 *
 * The device flow (RFC 8628) is used because a self-hosted server's domain cannot be pre-registered as
 * a redirect URI on the shared app registration, so an authorization-code callback can never come back
 * to it. With the device flow there is no redirect at all: the user enters a short code at Microsoft's
 * sign-in page in any browser while the client polls until the tokens arrive. (The desktop build does
 * not use these sign-in endpoints — it runs an authorization-code flow over a loopback redirect in the
 * Electron main process, which Microsoft matches host-only, and only stores the result here.)
 *
 * Flow:
 *   1. POST /api/onenote-import/device-login -> { userCode, verificationUri, ... }   (shown to the user)
 *   2. POST /api/onenote-import/device-poll  -> { status: pending | connected | failed }   (client polls)
 *   3. GET  /api/onenote-import/status       -> { connected, account }
 *   4. GET  /api/onenote-import/notebooks    -> { notebooks }
 *   5. POST /api/onenote-import/import       -> { noteId }
 */

import type { OneNoteDeviceLogin, OneNoteDevicePollResult, OneNoteSectionSelection } from "@triliumnext/commons";
import { becca, getLog, ValidationError } from "@triliumnext/core";
import type { Request } from "express";

import { isInternalElectronRequest } from "../../services/electron_request.js";
import { getDesktopSession, type OneNoteTokenSession, setDesktopSession } from "../../services/import/onenote/desktop_session.js";
import graph, { type AccessTokenProvider } from "../../services/import/onenote/graph.js";
import importer from "../../services/import/onenote/importer.js";
import { ONENOTE_OAUTH } from "../../services/import/onenote/oauth.js";
import { createGraphTokenProvider } from "../../services/import/onenote/token_provider.js";
import oauth, { type DevicePollResult } from "../../services/oauth/oauth.js";

async function deviceLogin(req: Request): Promise<OneNoteDeviceLogin> {
    const device = await oauth.requestDeviceCode(ONENOTE_OAUTH);

    // Starting a new sign-in discards any previous connection or half-finished attempt. Only the
    // device code (the credential the tokens are polled out with) stays server-side; the browser gets
    // exclusively the user-facing pieces.
    req.session.oneNoteImport = {
        deviceCode: device.device_code,
        deviceCodeExpiresAt: Date.now() + device.expires_in * 1000
    };
    await saveSession(req);

    return {
        userCode: device.user_code,
        verificationUri: device.verification_uri,
        expiresInSeconds: device.expires_in,
        intervalSeconds: device.interval
    };
}

async function devicePoll(req: Request): Promise<OneNoteDevicePollResult | [number, string]> {
    const pending = req.session.oneNoteImport;

    // A concurrent/earlier poll may have already completed the sign-in. Report that instead of polling
    // the now-consumed device code again (which would fail and could wipe the good tokens).
    if (pending?.accessToken) {
        return { status: "connected", account: pending.account ?? EMPTY_ACCOUNT };
    }
    if (!pending?.deviceCode) {
        return [400, "No sign-in is in progress."];
    }

    const clearPending = async () => {
        delete req.session.oneNoteImport;
        await saveSession(req);
    };

    if (pending.deviceCodeExpiresAt && Date.now() > pending.deviceCodeExpiresAt) {
        await clearPending();
        return { status: "failed", error: "The sign-in code expired before the sign-in was completed. Please try again." };
    }

    let result: DevicePollResult;
    try {
        result = await oauth.pollDeviceToken(ONENOTE_OAUTH, pending.deviceCode);
    } catch (e) {
        // pollDeviceToken throws only on a known terminal outcome (declined, code expired): the device
        // code is dead, so the pending state is too and the client offers a fresh sign-in. Transient
        // failures come back as `pending`, never here, so a network blip won't cancel a valid sign-in.
        await clearPending();
        return { status: "failed", error: e instanceof Error ? e.message : String(e) };
    }

    if (result.status === "pending") {
        return { status: "pending", slowDown: result.slowDown };
    }

    // Success consumes the device code, so the tokens can't be re-fetched by polling again — persist
    // them immediately, before the (fallible, non-essential) profile lookup, so a transient failure
    // there can't discard a completed sign-in.
    req.session.oneNoteImport = {
        accessToken: result.tokens.access_token,
        refreshToken: result.tokens.refresh_token,
        expiresAt: Date.now() + result.tokens.expires_in * 1000
    };
    await saveSession(req);

    let account = EMPTY_ACCOUNT;
    try {
        account = await graph.getAccount(() => Promise.resolve(result.tokens.access_token));
        req.session.oneNoteImport = { ...req.session.oneNoteImport, account };
        await saveSession(req);
    } catch (e) {
        // The connection stands (tokens are stored); only the display name is missing. Leave it blank
        // rather than failing the whole sign-in over a cosmetic profile fetch.
        getLog().info(`OneNote sign-in connected but the profile lookup failed: ${e instanceof Error ? e.message : String(e)}`);
    }

    return { status: "connected", account };
}

const EMPTY_ACCOUNT = { name: "", email: "" };

function getStatus(req: Request) {
    const session = tokenStore(req).read();
    return { connected: !!session?.accessToken, account: session?.account ?? null };
}

async function disconnect(req: Request) {
    await tokenStore(req).clear();
    return {};
}

async function getNotebooks(req: Request) {
    const getAccessToken = buildTokenProvider(req);
    const failure = await connectionFailure(getAccessToken);
    if (failure) {
        return [401, failure];
    }
    return { notebooks: await graph.listNotebooks(getAccessToken) };
}

async function runImport(req: Request) {
    const getAccessToken = buildTokenProvider(req);
    const failure = await connectionFailure(getAccessToken);
    if (failure) {
        return [401, failure];
    }

    const { parentNoteId, sections, taskId, debug, shrinkImages } = req.body as { parentNoteId: string; sections: OneNoteSectionSelection[]; taskId: string; debug?: boolean; shrinkImages?: boolean };
    if (!parentNoteId || !taskId) {
        throw new ValidationError("parentNoteId and taskId are required.");
    }
    if (!Array.isArray(sections) || sections.length === 0) {
        return [400, "No sections were selected."];
    }
    becca.getNoteOrThrow(parentNoteId);

    // Fire-and-forget: a large notebook can take far longer than the client's HTTP request timeout, so
    // we return immediately and let the import report progress, completion and any error over the
    // WebSocket (taskType "importNotes"). importSelection catches and reports its own failures, so the
    // detached promise never rejects. The token provider (not a fixed token) is handed off so the
    // import keeps refreshing across its whole run, which can outlast a single Graph token.
    void importer.importSelection({ getAccessToken, parentNoteId, sections, taskId, debug: !!debug, shrinkImages: !!shrinkImages });
    return {};
}

/**
 * Builds the token provider bound to this request's token store (session on web, the process-wide
 * singleton on desktop). Returns a valid access token per call, refreshing and persisting as expiry
 * nears; the importer re-reads it before every Graph request so a long import never runs on an expired
 * token. See {@link createGraphTokenProvider}.
 */
function buildTokenProvider(req: Request): AccessTokenProvider {
    const store = tokenStore(req);
    return createGraphTokenProvider({
        read: () => store.read(),
        write: (tokens) => store.write(tokens),
        refresh: (refreshToken) => oauth.refreshAccessToken(ONENOTE_OAUTH, { refreshToken })
    });
}

/**
 * The reason the connection cannot currently produce an access token, or null when it can.
 *
 * The message is passed through to the client rather than flattened into a generic "not connected",
 * because a stored-but-unrefreshable token is the case that matters: /status reports the connection as
 * live (it only sees that a token is stored), so without this reason the notebook list comes back empty
 * and the dialog can only say the account has no notebooks. The token provider's messages already tell
 * the user to sign in again.
 */
async function connectionFailure(getAccessToken: AccessTokenProvider): Promise<string | null> {
    try {
        await getAccessToken();
        return null;
    } catch (e) {
        const reason = e instanceof Error ? e.message : String(e);
        getLog().info(`OneNote import: the stored connection could not produce an access token: ${reason}`);
        return reason || "Not connected to OneNote.";
    }
}

interface TokenStore {
    read(): OneNoteTokenSession | undefined;
    /** Merges `data` into the stored token, preserving fields (e.g. the account) not being updated. */
    write(data: OneNoteTokenSession): Promise<void>;
    clear(): Promise<void>;
}

/**
 * Picks where the connected Graph token lives. Desktop renderer requests arrive over the
 * `trilium-app://` protocol dispatch (tagged as internal-electron) and use the process-wide
 * {@link getDesktopSession} singleton, because their OAuth callback was handled out-of-band by the
 * main process and never touched this session. Every other request keeps the token in its own
 * express-session, the same browser that completed the callback.
 */
function tokenStore(req: Request): TokenStore {
    if (isInternalElectronRequest(req)) {
        return {
            read: () => getDesktopSession() ?? undefined,
            write: async (data) => setDesktopSession({ ...getDesktopSession(), ...data }),
            clear: async () => setDesktopSession(null)
        };
    }
    return {
        read: () => req.session.oneNoteImport,
        write: async (data) => {
            req.session.oneNoteImport = { ...req.session.oneNoteImport, ...data };
            await saveSession(req);
        },
        clear: async () => {
            delete req.session.oneNoteImport;
            await saveSession(req);
        }
    };
}

function saveSession(req: Request): Promise<void> {
    return new Promise((resolve, reject) => req.session.save((err) => (err ? reject(err) : resolve())));
}

export default {
    deviceLogin,
    devicePoll,
    getStatus,
    disconnect,
    getNotebooks,
    runImport
};