dsh-plugin-onenote 0.0.0-stage → 0.2.2

package/src/permissions.js

@@ -0,0 +1,108 @@
+/**
+ * Notebook consent: the allow-list and the guard every reading tool runs first.
+ *
+ * This module is the privacy boundary. Nothing that reads note content may call
+ * Microsoft Graph before {@link assertNotebookAllowed} has confirmed the owning
+ * notebook was explicitly chosen by the user, so a prompt-injected page id can
+ * never reach a notebook that was not consented to.
+ */
+import { readAllowedNotebooks, writeAllowedNotebooks } from './state.js';
+
+/** Error code used when a notebook was not consented to. */
+export const NOT_ALLOWED = 'NOTEBOOK_NOT_ALLOWED';
+
+/** A denial the tools surface verbatim, with the recovery step included. */
+export class NotebookNotAllowedError extends Error {
+  constructor(notebookNameOrId) {
+    super(
+      `Notebook "${notebookNameOrId}" is not in the allowed list, so its content is not readable. ` +
+        'The user chooses readable notebooks in Settings → Plugins → OneNote; ask them to add it there if they want it read.',
+    );
+    this.name = 'NotebookNotAllowedError';
+    this.code = NOT_ALLOWED;
+  }
+}
+
+/** The current allow-list, read fresh so an edit through another path takes effect. */
+export function allowedNotebooks() {
+  return readAllowedNotebooks();
+}
+
+/** Whether the allow-list is still empty, i.e. the user has not chosen yet. */
+export function hasConsent() {
+  return readAllowedNotebooks().length > 0;
+}
+
+/**
+ * Normalize one id for comparison. Graph ids are case-insensitive GUIDs, and a
+ * notebook id may arrive percent-encoded inside a page or section URL.
+ */
+function normalizeId(value) {
+  if (typeof value !== 'string') return '';
+  let id = value.trim();
+  if (id.length === 0) return '';
+  try {
+    if (id.includes('%')) id = decodeURIComponent(id);
+  } catch {
+    /* a malformed escape stays as written and simply fails the comparison */
+  }
+  return id.toLowerCase();
+}
+
+/** Whether a notebook id is allowed. */
+export function isNotebookAllowed(notebookId) {
+  const wanted = normalizeId(notebookId);
+  if (wanted.length === 0) return false;
+  return allowedNotebooks().some((entry) => normalizeId(entry.id) === wanted);
+}
+
+/**
+ * Throw unless the notebook is allowed.
+ * @param {string} notebookId - the owning notebook id.
+ * @param {string} [label] - a name to use in the denial message.
+ * @returns {{ id: string, name: string }} the matching allow-list entry.
+ */
+export function assertNotebookAllowed(notebookId, label) {
+  const wanted = normalizeId(notebookId);
+  const match = allowedNotebooks().find((entry) => normalizeId(entry.id) === wanted);
+  if (match === undefined) throw new NotebookNotAllowedError(label ?? notebookId);
+  return match;
+}
+
+/**
+ * Resolve the notebook that owns a section, then assert consent.
+ * Graph does not return a section's notebook on every payload, so callers pass
+ * the notebook id they already know when they have it.
+ * @param {string} notebookId - the owning notebook id.
+ * @param {string} [label] - a name for the denial message.
+ */
+export function assertNotebookAllowedForSection(notebookId, label) {
+  return assertNotebookAllowed(notebookId, label);
+}
+
+/**
+ * Replace the allow-list with the chosen notebooks.
+ * @param {readonly { id: string, name?: string }[]} notebooks - chosen notebooks.
+ * @returns {{ id: string, name: string }[]} the stored entries.
+ */
+export function setAllowedNotebooks(notebooks) {
+  const seen = new Set();
+  const stored = [];
+  for (const notebook of notebooks ?? []) {
+    if (notebook === null || typeof notebook !== 'object') continue;
+    const id = typeof notebook.id === 'string' ? notebook.id.trim() : '';
+    const key = normalizeId(id);
+    if (key.length === 0 || seen.has(key)) continue;
+    seen.add(key);
+    const name = typeof notebook.name === 'string' && notebook.name.trim().length > 0 ? notebook.name.trim() : id;
+    stored.push({ id, name });
+  }
+  writeAllowedNotebooks(stored);
+  return stored;
+}
+
+/** Forget every consent, so nothing is readable until the user chooses again. */
+export function clearAllowedNotebooks() {
+  writeAllowedNotebooks([]);
+  return [];
+}

package/src/routes.js

@@ -0,0 +1,166 @@
+/**
+ * Browser routes for the settings card.
+ *
+ * The card cannot import Host code, so it talks to this module over the Web
+ * server's own origin. Every route answers JSON and never throws: a handler
+ * failure becomes `{ ok: false, error }` so the card can show a message instead
+ * of a dead panel.
+ *
+ * Sign-in and consent changes are reachable ONLY here. The agent tools never
+ * expose them, which keeps "who may widen my read scope" a user decision.
+ */
+import { describeFailure, OneNoteError } from './service.js';
+
+const PREFIX = '/api/onenote';
+const MAX_BODY_BYTES = 64 * 1024;
+
+/**
+ * A route table entry: method, path, and the body it accepts.
+ *
+ * Each path appears once: the Web server rejects a duplicate `(kind, path)`
+ * pair, so a second method on the same path needs its own path segment.
+ */
+const ROUTES = [
+  { method: 'GET', path: `${PREFIX}/state`, run: (service) => stateOf(service) },
+  { method: 'POST', path: `${PREFIX}/device-code/start`, run: (service) => beginSignIn(service) },
+  { method: 'GET', path: `${PREFIX}/device-code`, run: (service) => pollSignIn(service) },
+  { method: 'POST', path: `${PREFIX}/notebooks`, run: (service, body) => saveNotebooks(service, body) },
+  { method: 'POST', path: `${PREFIX}/sign-out`, run: (service) => signOut(service) },
+];
+
+function send(res, status, payload) {
+  res.writeHead(status, {
+    'content-type': 'application/json; charset=utf-8',
+    'cache-control': 'no-store',
+  });
+  res.end(JSON.stringify(payload));
+}
+
+async function readJsonBody(req) {
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of req) {
+    size += chunk.length;
+    if (size > MAX_BODY_BYTES) throw new OneNoteError('The request body is too large.', 'BODY_TOO_LARGE');
+    chunks.push(chunk);
+  }
+  if (chunks.length === 0) return {};
+  const text = Buffer.concat(chunks).toString('utf8').trim();
+  if (text.length === 0) return {};
+  try {
+    const parsed = JSON.parse(text);
+    return parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+  } catch {
+    throw new OneNoteError('The request body is not valid JSON.', 'INVALID_BODY');
+  }
+}
+
+/** The settings card's whole view of the plugin, in one request. */
+async function stateOf(service) {
+  const status = service.status();
+  const base = {
+    ok: true,
+    signedIn: status.signedIn,
+    renewsAutomatically: status.renewsAutomatically,
+    expiresAt: status.expiresAt,
+    account: status.account,
+    allowedCount: status.allowedCount,
+    allowedNotebooks: status.allowedNotebooks,
+    pendingSignIn: status.pendingSignIn,
+    notebooks: [],
+    notebooksError: undefined,
+  };
+  // The notebook list needs a live token; signed out, the card still renders.
+  if (!status.signedIn) return base;
+  try {
+    base.notebooks = await service.listNotebooks();
+  } catch (error) {
+    base.notebooksError = describeFailure(error);
+  }
+  return base;
+}
+
+async function beginSignIn(service) {
+  const started = await service.beginSignIn();
+  return { ok: true, ...started };
+}
+
+async function pollSignIn(service) {
+  const outcome = await service.pollSignIn();
+  if (outcome.status === 'signed-in') {
+    return { ...(await stateOf(service)), status: 'signed-in', account: outcome.account };
+  }
+  return { ok: true, status: outcome.status, expiresInSeconds: outcome.expiresInSeconds };
+}
+
+async function saveNotebooks(service, body) {
+  if (body.action === 'clear') {
+    service.clearAllowedNotebooks();
+    return { ...(await stateOf(service)), allowedCount: 0 };
+  }
+  const ids = Array.isArray(body.allowedIds) ? body.allowedIds : [];
+  const stored = await service.setAllowedNotebooks(ids);
+  return { ...(await stateOf(service)), allowedCount: stored.length };
+}
+
+function signOut(service) {
+  service.signOut();
+  return {
+    ok: true,
+    signedIn: false,
+    allowedCount: service.allowedNotebooks().length,
+  };
+}
+
+/**
+ * Register every route on the Web server.
+ *
+ * Call this from inside `ctx.inject(['webServer'], ...)`, never directly from
+ * `apply`. The Loader starts every row concurrently and the webServer row is
+ * still LOADING while it binds its socket, so `ctx.get('webServer')` at apply
+ * time answers `undefined` and every route is skipped. The card then falls
+ * through to Connection's `/api` prefix, which answers a plain-text 401 that is
+ * not JSON, and the card shows an error instead of the sign-in form.
+ *
+ * @param {object} ctx - the plugin context, whose `webServer` may be absent.
+ * @param {object} service - the shared OneNote service.
+ * @returns {boolean} whether the routes were registered.
+ */
+export function installRoutes(ctx, service) {
+  const webServer = ctx.get('webServer');
+  if (webServer === undefined) {
+    ctx.logger?.warn?.('onenote: no web server in this composition, so the settings card has no data source; the tools still work.');
+    return false;
+  }
+
+  for (const route of ROUTES) {
+    ctx.effect(() => webServer.register({
+      kind: 'exact',
+      path: route.path,
+      handler: async (req, res) => {
+        if (req.method !== route.method) {
+          send(res, 405, { ok: false, error: `Use ${route.method} for this endpoint.` });
+          return;
+        }
+        try {
+          const body = route.method === 'POST' ? await readJsonBody(req) : {};
+          const payload = await route.run(service, body);
+          // `ok: true` is authoritative even when a spread carried `ok: false`.
+          send(res, 200, { ...payload, ok: true });
+        } catch (error) {
+          send(res, 200, { ok: false, error: describeFailure(error), code: error?.code });
+        }
+      },
+    }), `onenote route ${route.method} ${route.path}`);
+  }
+  return true;
+}
+
+/** The endpoint paths, exported so tests and the client share one source. */
+export const ENDPOINTS = {
+  state: `${PREFIX}/state`,
+  startDeviceCode: `${PREFIX}/device-code/start`,
+  pollDeviceCode: `${PREFIX}/device-code`,
+  notebooks: `${PREFIX}/notebooks`,
+  signOut: `${PREFIX}/sign-out`,
+};

package/src/service.js

@@ -0,0 +1,393 @@
+/**
+ * The one implementation of every OneNote operation.
+ *
+ * Both callers go through here: the agent tools in `tools.js` and the browser
+ * routes in `routes.js`. Neither re-implements a Graph call or a consent check,
+ * so the two surfaces can never disagree about what is allowed.
+ *
+ * Consent is enforced inside this module, not by its callers: every read path
+ * resolves the owning notebook and asserts the allow-list before touching page
+ * content, so a page id guessed by a model or injected into a note still cannot
+ * reach an unapproved notebook.
+ */
+import {
+  OneNoteAuthError,
+  pollDeviceCodeOnce,
+  rememberAccount,
+  signInSummary,
+  signOut,
+  startDeviceCode,
+} from './auth.js';
+import {
+  getMe,
+  getPageContent,
+  getPageMeta,
+  getSectionMeta,
+  GraphError,
+  listNotebooks,
+  listPagesInNotebook,
+  listPagesInSection,
+  listSections,
+} from './graph-client.js';
+import { htmlToPlainText, renderPage } from './parser.js';
+import {
+  allowedNotebooks,
+  assertNotebookAllowed,
+  clearAllowedNotebooks,
+  hasConsent,
+  isNotebookAllowed,
+  NotebookNotAllowedError,
+  setAllowedNotebooks,
+} from './permissions.js';
+import { readPendingSignIn, writePendingSignIn } from './state.js';
+
+/** Page-metadata scan budget for a search, and how many bodies it opens. */
+const SEARCH_PAGE_SCAN = 300;
+const SEARCH_BODY_SCAN = 15;
+const SEARCH_SNIPPET_CHARS = 220;
+
+/** A failure whose message is already written for a person to read. */
+export class OneNoteError extends Error {
+  constructor(message, code) {
+    super(message);
+    this.name = 'OneNoteError';
+    this.code = code;
+  }
+}
+
+/**
+ * Reduce any thrown value to one actionable sentence.
+ * @param {unknown} error - whatever was thrown.
+ * @returns {string} a message safe to show a model or a browser.
+ */
+export function describeFailure(error) {
+  if (error instanceof NotebookNotAllowedError) return `Notebook not allowed. ${error.message}`;
+  if (error instanceof OneNoteAuthError) return `OneNote sign-in needed. ${error.message}`;
+  if (error instanceof GraphError) return `OneNote request failed. ${error.message}`;
+  if (error instanceof OneNoteError) return error.message;
+  if (error instanceof Error) return `OneNote operation failed. ${error.message}`;
+  return `OneNote operation failed. ${String(error)}`;
+}
+
+/** Copy only defined fields, so no property holds `undefined`. */
+function compact(source) {
+  const out = {};
+  for (const [key, value] of Object.entries(source)) {
+    if (value !== undefined) out[key] = value;
+  }
+  return out;
+}
+
+function clampInt(value, fallback, min = 1, max = 200) {
+  if (typeof value !== 'number' || !Number.isFinite(value)) return fallback;
+  return Math.min(max, Math.max(min, Math.trunc(value)));
+}
+
+function pageItem(page) {
+  return compact({
+    id: page.id,
+    title: page.title,
+    lastModified: page.lastModified,
+    sectionName: page.sectionName,
+    notebookName: page.notebookName,
+    webUrl: page.webUrl,
+  });
+}
+
+function sectionItem(section) {
+  return { id: section.id, name: section.name };
+}
+
+/**
+ * Build the service over one resolved plugin config.
+ * @param {{ clientId: string, tenant: string, maxPagesPerList: number, maxPageChars: number }} config - resolved config.
+ * @returns {object} the operations shared by tools and routes.
+ */
+export function createOneNoteService(config) {
+  return {
+    /** Sign-in and consent status, for the tool and the settings card. */
+    status() {
+      const summary = signInSummary();
+      const allowed = allowedNotebooks();
+      return {
+        signedIn: summary.signedIn,
+        renewsAutomatically: summary.renewsAutomatically === true,
+        expiresAt: summary.expiresAt,
+        account: summary.account,
+        allowedCount: allowed.length,
+        allowedNotebooks: allowed.map((entry) => ({ id: entry.id, name: entry.name })),
+        pendingSignIn: readPendingSignIn() !== undefined,
+      };
+    },
+
+    /** Start (or continue) a device-code attempt and return what to show the user. */
+    async beginSignIn() {
+      const pending = readPendingSignIn();
+      if (pending !== undefined) {
+        return {
+          userCode: pending.userCode,
+          verificationUri: pending.verificationUri,
+          expiresInSeconds: Math.max(0, Math.round((pending.expiresAt - Date.now()) / 1000)),
+        };
+      }
+      const started = await startDeviceCode(config);
+      // Persist before returning: the next call is a separate HTTP request, so
+      // the attempt must survive this one.
+      writePendingSignIn(started);
+      return {
+        userCode: started.userCode,
+        verificationUri: started.verificationUri,
+        expiresInSeconds: Math.max(0, Math.round((started.expiresAt - Date.now()) / 1000)),
+      };
+    },
+
+    /**
+     * Poll the pending attempt exactly once.
+     *
+     * One poll per call keeps an HTTP request short: the browser repeats it,
+     * so the user sees a live countdown instead of a stalled request.
+     * @returns {Promise<object>} `pending`, `signed-in`, or a thrown auth error.
+     */
+    async pollSignIn() {
+      const pending = readPendingSignIn();
+      if (pending === undefined) {
+        const summary = signInSummary();
+        if (summary.signedIn) return { status: 'signed-in', account: summary.account };
+        return { status: 'expired' };
+      }
+      const outcome = await pollDeviceCodeOnce(pending);
+      if (outcome.status === 'pending') {
+        return {
+          status: 'pending',
+          expiresInSeconds: Math.max(0, Math.round((pending.expiresAt - Date.now()) / 1000)),
+        };
+      }
+      return await this.completeSignIn();
+    },
+
+    /** Read the profile once the token is stored, so the card can name the account. */
+    async completeSignIn() {
+      const summary = signInSummary();
+      try {
+        const me = await getMe(config);
+        rememberAccount(me);
+        return { status: 'signed-in', account: me };
+      } catch (error) {
+        // The token is already stored; a profile read failure must not read as a failed sign-in.
+        if (error instanceof GraphError) return { status: 'signed-in', account: summary.account };
+        throw error;
+      }
+    },
+
+    /** Forget the stored session. The allow-list is deliberately untouched. */
+    signOut() {
+      signOut();
+    },
+
+    /**
+     * Every notebook the account can see, flagged with whether it is allowed.
+     * This is the only read that deliberately looks outside the allow-list: the
+     * user has to see the names in order to choose.
+     */
+    async listNotebooks() {
+      const notebooks = await listNotebooks(config);
+      return notebooks.map((notebook) => compact({
+        id: notebook.id,
+        name: notebook.name,
+        allowed: isNotebookAllowed(notebook.id),
+        isDefault: notebook.isDefault || undefined,
+        isShared: notebook.isShared || undefined,
+        lastModified: notebook.lastModified,
+      }));
+    },
+
+    /**
+     * Replace the allow-list. Only a user action may call this: the tools never
+     * expose it, so a prompt-injected note cannot widen its own read scope.
+     * @param {readonly string[]} ids - notebook ids to allow.
+     * @returns {Promise<object[]>} the stored entries.
+     */
+    async setAllowedNotebooks(ids) {
+      const requested = Array.isArray(ids) ? ids.filter((id) => typeof id === 'string' && id.trim().length > 0) : [];
+      if (requested.length === 0) {
+        clearAllowedNotebooks();
+        return [];
+      }
+      const available = await listNotebooks(config);
+      const byId = new Map(available.map((notebook) => [notebook.id.toLowerCase(), notebook]));
+      const unknown = requested.filter((id) => !byId.has(id.trim().toLowerCase()));
+      if (unknown.length > 0) {
+        throw new OneNoteError(
+          `These notebook ids are not visible to the signed-in account: ${unknown.join(', ')}. Refresh the list and try again.`,
+          'UNKNOWN_NOTEBOOK',
+        );
+      }
+      return setAllowedNotebooks(requested.map((id) => {
+        const notebook = byId.get(id.trim().toLowerCase());
+        return { id: notebook.id, name: notebook.name };
+      }));
+    },
+
+    /** Forget every consent. */
+    clearAllowedNotebooks() {
+      clearAllowedNotebooks();
+    },
+
+    /** Whether any notebook is readable right now. */
+    hasConsent,
+
+    /** The readable notebooks, as stored. */
+    allowedNotebooks,
+
+    /**
+     * Browse allowed structure: no arguments lists notebooks with sections;
+     * `notebookId` adds its pages; `sectionId` returns that section's pages.
+     * @param {{ notebookId?: string, sectionId?: string, limit?: number }} input - the browse target.
+     * @param {AbortSignal} [signal] - caller cancellation.
+     */
+    async listPages(input, signal) {
+      const limit = clampInt(input.limit, Math.min(50, config.maxPagesPerList), 1, 200);
+      if (!hasConsent()) {
+        return { message: 'No notebooks are allowed yet. Open Settings → Plugins → OneNote to choose which notebooks this agent may read.' };
+      }
+
+      if (typeof input.sectionId === 'string' && input.sectionId.trim().length > 0) {
+        const sectionId = input.sectionId.trim();
+        // Resolve the owner before listing: a guessed section id must not read
+        // pages from a notebook the user never approved.
+        const section = await getSectionMeta(config, sectionId, signal);
+        if (section.notebookId === undefined) {
+          throw new OneNoteError('Microsoft Graph did not report which notebook owns this section, so it cannot be checked against the allowed list.', 'UNVERIFIABLE_OWNER');
+        }
+        assertNotebookAllowed(section.notebookId);
+        const pages = await listPagesInSection(config, sectionId, signal, limit);
+        return {
+          message: pages.length === 0 ? `Section ${section.name} has no pages.` : `${pages.length} page(s) in section ${section.name}.`,
+          pages: pages.map(pageItem),
+        };
+      }
+
+      if (typeof input.notebookId === 'string' && input.notebookId.trim().length > 0) {
+        const allowed = assertNotebookAllowed(input.notebookId.trim());
+        const sections = await listSections(config, allowed.id, signal);
+        const pages = await listPagesInNotebook(config, allowed.id, signal, limit);
+        return {
+          message: `Notebook ${allowed.name}: ${sections.length} section(s), ${pages.length} page(s).`,
+          notebooks: [{ id: allowed.id, name: allowed.name, sections: sections.map(sectionItem) }],
+          pages: pages.map(pageItem),
+        };
+      }
+
+      const notebooks = [];
+      for (const allowed of allowedNotebooks()) {
+        const sections = await listSections(config, allowed.id, signal);
+        notebooks.push({ id: allowed.id, name: allowed.name, sections: sections.map(sectionItem) });
+      }
+      return {
+        message: `${notebooks.length} allowed notebook(s). Pass notebook_id or section_id to list pages.`,
+        notebooks,
+      };
+    },
+
+    /**
+     * Search the allowed notebooks: titles first, then the opening text of the
+     * most recently modified pages. OneNote's server-side page search was
+     * retired in 2024, so matching happens here, bounded to the allowed set.
+     * @param {{ query: string, limit?: number }} input - the search.
+     * @param {AbortSignal} [signal] - caller cancellation.
+     */
+    async search(input, signal) {
+      const query = typeof input.query === 'string' ? input.query.trim() : '';
+      if (query.length === 0) throw new OneNoteError('A search needs a non-empty query.', 'EMPTY_QUERY');
+      const limit = clampInt(input.limit, 10, 1, 50);
+      const needle = query.toLowerCase();
+      const allowed = allowedNotebooks();
+      if (allowed.length === 0) {
+        return { message: 'No notebooks are allowed yet. Open Settings → Plugins → OneNote to choose notebooks first.' };
+      }
+
+      const candidates = [];
+      for (const notebook of allowed) {
+        const pages = await listPagesInNotebook(config, notebook.id, signal, SEARCH_PAGE_SCAN);
+        for (const page of pages) candidates.push({ page, notebook });
+      }
+      candidates.sort((left, right) => String(right.page.lastModified ?? '').localeCompare(String(left.page.lastModified ?? '')));
+
+      const results = [];
+      const seen = new Set();
+      const add = (page, notebook, matchedIn, snippet) => {
+        if (seen.has(page.id) || results.length >= limit) return;
+        seen.add(page.id);
+        results.push(compact({
+          id: page.id,
+          title: page.title,
+          notebookName: notebook.name,
+          sectionName: page.sectionName,
+          lastModified: page.lastModified,
+          matchedIn,
+          snippet,
+        }));
+      };
+
+      for (const { page, notebook } of candidates) {
+        if (results.length >= limit) break;
+        if (page.title.toLowerCase().includes(needle)) add(page, notebook, 'title');
+      }
+
+      if (results.length < limit) {
+        let scanned = 0;
+        for (const { page, notebook } of candidates) {
+          if (results.length >= limit || scanned >= SEARCH_BODY_SCAN) break;
+          if (seen.has(page.id)) continue;
+          scanned += 1;
+          try {
+            const plain = htmlToPlainText(await getPageContent(config, page.id, signal));
+            const at = plain.toLowerCase().indexOf(needle);
+            if (at < 0) continue;
+            const start = Math.max(0, at - 60);
+            add(page, notebook, 'body', plain.slice(start, start + SEARCH_SNIPPET_CHARS).trim());
+          } catch (error) {
+            // One unreadable page must not fail the search, but a dead session must.
+            if (error instanceof OneNoteAuthError) throw error;
+          }
+        }
+      }
+
+      return results.length === 0
+        ? { message: `No page in the allowed notebooks matched "${query}".` }
+        : { message: `Found ${results.length} matching page(s) for "${query}".`, results };
+    },
+
+    /**
+     * Read one page as Markdown, refusing any page outside the allow-list.
+     * @param {{ pageId: string, maxChars?: number }} input - the page to read.
+     * @param {AbortSignal} [signal] - caller cancellation.
+     */
+    async readPage(input, signal) {
+      const pageId = typeof input.pageId === 'string' ? input.pageId.trim() : '';
+      if (pageId.length === 0) throw new OneNoteError('Reading a page needs a page id.', 'EMPTY_PAGE_ID');
+      const maxChars = clampInt(input.maxChars, config.maxPageChars, 2000, 200000);
+
+      const meta = await getPageMeta(config, pageId, signal);
+      if (meta.notebookId === undefined) {
+        throw new OneNoteError(
+          'Microsoft Graph did not report which notebook owns this page, so it cannot be checked against the allowed list. List the page from its notebook to get an id that carries its notebook.',
+          'UNVERIFIABLE_OWNER',
+        );
+      }
+      const allowed = assertNotebookAllowed(meta.notebookId, meta.notebookName);
+      const html = await getPageContent(config, pageId, signal);
+      const rendered = renderPage(html, maxChars);
+      return compact({
+        id: meta.id,
+        title: meta.title,
+        notebookName: allowed.name,
+        sectionName: meta.sectionName,
+        lastModified: meta.lastModified,
+        webUrl: meta.webUrl,
+        truncated: rendered.truncated,
+        content: rendered.content.length > 0 ? rendered.content : '(this page has no readable text)',
+      });
+    },
+  };
+}