@openparachute/vault 0.6.0 → 0.6.1

package/src/mirror-routes.ts

@@ -24,8 +24,11 @@
  * hand + restarting the vault.
  */
 
+import { existsSync } from "node:fs";
+
 import {
   defaultMirrorConfig,
+  mirrorConfigPath,
   readMirrorConfigForVault,
   validateExternalPath,
   validateMirrorConfigShape,
@@ -46,11 +49,17 @@ import {
   type MirrorCredentials,
 } from "./mirror-credentials.ts";
 import {
+  GITHUB_APP_SLUG_DEFAULT,
+  GITHUB_CLIENT_ID_DEFAULT,
+  GitHubApiError,
   createRepo,
   fetchUser,
+  getGithubAppSlug,
   getGithubClientId,
+  installUrlForSlug,
   isPlaceholderClientId,
-  listRepos,
+  listInstallationRepos,
+  listInstallations,
   pollForToken,
   requestDeviceCode,
   type FetchLike,
@@ -298,9 +307,10 @@ export function buildMirrorGetResponse(
 }
 
 // ---------------------------------------------------------------------------
-// Credential routes — Cut 3 of the UI-configurable push credentials work.
+// Credential routes — Cut 3 of the UI-configurable push credentials work,
+// reshaped by the GitHub-App installation semantics (vault#480).
 //
-// Six surfaces, all `vault:<name>:admin`-gated upstream:
+// Surfaces, all `vault:<name>:admin`-gated upstream:
 //
 //   POST   /.parachute/mirror/auth/github/device-code  — start GitHub Device
 //          Flow; returns { polling_id, user_code, verification_uri, expires_in,
@@ -308,19 +318,29 @@ export function buildMirrorGetResponse(
 //          by polling_id (a short opaque token) so the device_code doesn't
 //          land on the wire twice.
 //   POST   /.parachute/mirror/auth/github/poll         — poll for token, body
-//          { polling_id }. On `granted`: fetch user, save credentials, set
-//          remote URL, return { state: "granted", user }. Other states
-//          surface verbatim.
+//          { polling_id }. On `granted`: fetch user, save credentials, enable
+//          history for a never-configured vault (vault#483), return
+//          { state: "granted", user, history_enabled }. Other states surface
+//          verbatim.
 //   POST   /.parachute/mirror/auth/pat                 — validate + store a
 //          PAT (token + remote_url + label). Validates via `git ls-remote`.
+//          Same history-on-link behavior as the poll grant (vault#483).
 //   GET    /.parachute/mirror/auth                     — current connection
-//          status (NO secrets). Returns the sanitized public shape.
+//          status (NO secrets, NO network). Returns the sanitized public shape.
 //   DELETE /.parachute/mirror/auth                     — wipe credentials,
 //          unset embedded-credential remote URL.
-//   GET    /.parachute/mirror/auth/github/repos        — list operator's
-//          GitHub repos via stored OAuth token.
+//   GET    /.parachute/mirror/auth/github/installations — install state
+//          (vault#480): which app, whether it's installed anywhere, the
+//          install link, and the per-account installations. The one
+//          explicitly-network status endpoint — `GET /auth` stays offline.
+//   GET    /.parachute/mirror/auth/github/repos        — list the repos the
+//          operator's app INSTALLATIONS grant (user + org accounts), via the
+//          stored OAuth token. Returns { installed: false, install_url,
+//          repos: [] } when the app isn't installed anywhere yet.
 //   POST   /.parachute/mirror/auth/github/create-repo  — create a new private
-//          repo on behalf of the operator.
+//          repo on behalf of the operator. 403s with the shared Contents-only
+//          app (mapped to error_type "app_lacks_admin_permission" + the
+//          guided-manual path); works for BYO apps with Administration:write.
 //
 // ---------------------------------------------------------------------------
 
@@ -363,16 +383,18 @@ export function _resetDeviceFlowSessionsForTest(): void {
 }
 
 /**
- * Errors out cleanly when the operator hasn't replaced the placeholder
- * client_id. The user-facing message explains the next step.
+ * Errors out cleanly when PARACHUTE_GITHUB_CLIENT_ID is set to a
+ * placeholder-shaped value. A real default ships in the build (the shared
+ * Parachute GitHub App — see github-device-flow.ts), so this is only
+ * reachable via a misconfigured override.
  */
 function placeholderClientIdResponse(): Response {
   return Response.json(
     {
-      error: "GitHub OAuth not configured",
+      error: "GitHub auth misconfigured",
       error_type: "placeholder_client_id",
       message:
-        "This Parachute Vault build doesn't have a registered GitHub OAuth App client_id. Set the PARACHUTE_GITHUB_CLIENT_ID environment variable (see src/github-device-flow.ts for setup steps) or use the Personal Access Token path instead.",
+        "PARACHUTE_GITHUB_CLIENT_ID is set to a placeholder value. Unset it to use the built-in shared Parachute GitHub App, set it to your own app's client_id, or use the Personal Access Token path instead.",
     },
     { status: 503 },
   );
@@ -515,12 +537,12 @@ export async function handleAuthGithubPoll(
     }
     // Clean up the polling session.
     deviceFlowSessions.delete(body.polling_id);
-    // Apply to git remote if mirror is currently running on an external
-    // path that's a git repo. The credentials become active on next push;
-    // the operator doesn't have to restart vault. We don't have an owner/
-    // repo yet (the operator hasn't picked a repo) — that wiring happens
-    // in the create-repo or repo-picked path. So at this point we just
-    // store credentials; the URL gets set when the operator picks a repo.
+    // vault#483: linking implies backup intent — enable history for a
+    // never-configured vault (consent-respecting; see the helper). No
+    // remote URL is set here — we don't have an owner/repo yet (the
+    // operator hasn't picked a repo); that wiring happens in select-repo,
+    // which is also where auto_push flips on (Cut 3).
+    const history_enabled = await maybeEnableHistoryOnLink(manager);
     return Response.json(
       {
         state: "granted",
@@ -530,6 +552,7 @@ export async function handleAuthGithubPoll(
           name: user.name,
           avatar_url: user.avatar_url,
         },
+        history_enabled,
       },
       { headers: { "Access-Control-Allow-Origin": "*" } },
     );
@@ -563,6 +586,14 @@ export async function handleAuthGithubPoll(
 export async function handleAuthPat(
   req: Request,
   manager: MirrorManager,
+  // Test seam for the `git ls-remote` validation probe (default
+  // `probeGitLsRemote`, which spawns real git against the supplied remote).
+  // Inject a fn returning `{ok: true}` to exercise the post-validation save
+  // path (credential persist + history-on-link, vault#483) hermetically.
+  probeOverride?: (
+    url: string,
+    timeoutMs: number,
+  ) => Promise<{ ok: boolean; error?: string }>,
 ): Promise<Response> {
   let body: { token?: unknown; remote_url?: unknown; label?: unknown };
   try {
@@ -657,7 +688,7 @@ export async function handleAuthPat(
           u.password = token;
           return u.toString();
         })();
-  const probeResult = await probeGitLsRemote(authedUrl, 10_000);
+  const probeResult = await (probeOverride ?? probeGitLsRemote)(authedUrl, 10_000);
   if (!probeResult.ok) {
     return Response.json(
       {
@@ -694,6 +725,15 @@ export async function handleAuthPat(
     );
   }
 
+  // vault#483: linking implies backup intent — enable history for a
+  // never-configured vault BEFORE the Cut-3/Cut-6 steps below, so a fresh
+  // vault gets the whole intended flow in one save: history on (the reload's
+  // start() applies the just-written PAT remote to `origin`), then Cut 3
+  // sees an enabled mirror and flips auto_push on, then Cut 6 fires the
+  // initial push. An explicitly-disabled mirror short-circuits all of it
+  // (history stays off → maybeEnableAutoPush no-ops on disabled).
+  const history_enabled = await maybeEnableHistoryOnLink(manager);
+
   // Push the new URL onto the mirror's git remote if it's currently
   // resolved + on disk. Non-fatal if the mirror isn't running.
   await applyCredentialsToMirror(manager);
@@ -713,6 +753,7 @@ export async function handleAuthPat(
   return Response.json(
     {
       ...sanitizeCredentials(next),
+      history_enabled,
       auto_push_was_already_enabled: autoPushChange.was_already_enabled,
       auto_push_enabled: autoPushChange.auto_push_now_enabled,
       initial_push: initialPush,
@@ -811,8 +852,102 @@ export async function handleAuthDelete(manager: MirrorManager): Promise<Response
 }
 
 /**
- * `GET /.parachute/mirror/auth/github/repos` — list operator's repos via
- * the stored OAuth token. Requires `active_method === "github_oauth"`.
+ * `GET /.parachute/mirror/auth/github/installations` — install state for
+ * the connect flow (vault#480). Answers three UI questions in one call:
+ * which app is in play (shared default vs BYO), is it installed ANYWHERE
+ * for this operator, and which accounts (user/orgs) carry installations.
+ *
+ * Deliberately a separate, explicitly-network endpoint: `GET /auth` stays
+ * a pure local read of the stored credential. The SPA calls this when it
+ * renders the connect flow / repo picker, not on every status poll.
+ *
+ * Response:
+ *   200 {
+ *     app: { client_id, slug, is_shared_default },
+ *     installed: boolean,            // installations.length > 0
+ *     install_url: string,           // github.com/apps/<slug>/installations/new
+ *     installations: [{ id, account_login, account_type, repository_selection }]
+ *   }
+ *   400 { error, error_type: "github_not_connected", message } — no stored
+ *       github_oauth credential; the device flow hasn't been run (or a PAT
+ *       is active instead — install state is a GitHub-App concept). 400,
+ *       not 401, matching the sibling repos handler: a 401 here would trip
+ *       the SPA's authedFetch token-refresh machinery and clear a
+ *       perfectly valid cached admin token over a non-auth condition.
+ *   502 { error, message } — GitHub unreachable / API error.
+ */
+export async function handleAuthGithubInstallations(
+  manager: MirrorManager,
+  fetchImpl?: FetchLike,
+): Promise<Response> {
+  const creds = readCredentials(manager.getVaultName());
+  if (!creds || creds.active_method !== "github_oauth" || !creds.github_oauth) {
+    return Response.json(
+      {
+        error: "Not connected to GitHub",
+        error_type: "github_not_connected",
+        message:
+          "No GitHub sign-in is stored for this vault. Run the device flow first (POST /.parachute/mirror/auth/github/device-code).",
+      },
+      { status: 400 },
+    );
+  }
+  const clientId = getGithubClientId();
+  const slug = getGithubAppSlug();
+  let installations;
+  try {
+    installations = await listInstallations(creds.github_oauth.access_token, fetchImpl);
+  } catch (err) {
+    return Response.json(
+      {
+        error: "Installation check failed",
+        message: (err as Error).message ?? String(err),
+      },
+      { status: 502 },
+    );
+  }
+  return Response.json(
+    {
+      app: {
+        client_id: clientId,
+        slug,
+        is_shared_default:
+          clientId === GITHUB_CLIENT_ID_DEFAULT && slug === GITHUB_APP_SLUG_DEFAULT,
+      },
+      installed: installations.length > 0,
+      install_url: installUrlForSlug(slug),
+      installations: installations.map((i) => ({
+        id: i.id,
+        account_login: i.account.login,
+        account_type: i.account.type,
+        repository_selection: i.repository_selection,
+      })),
+    },
+    { headers: { "Access-Control-Allow-Origin": "*" } },
+  );
+}
+
+/**
+ * `GET /.parachute/mirror/auth/github/repos` — list the repos the
+ * operator's app installations grant, via the stored OAuth token. Requires
+ * `active_method === "github_oauth"`.
+ *
+ * Source (vault#480): `GET /user/installations` → per-installation
+ * `GET /user/installations/{id}/repositories`, unioned. This replaces the
+ * old `GET /user/repos?type=owner` source, which (a) excluded org-owned
+ * repos by construction and (b) showed all-public-repos when the app wasn't
+ * installed at all (every GitHub App reads public repos) — Aaron walked
+ * into exactly that "looks connected, shows the wrong repos" state live.
+ *
+ * Response:
+ *   200 installed:    { installed: true, repos: [{ ...GitHubRepoInfo,
+ *                       account_login, installation_id }], truncated }
+ *   200 not installed: { installed: false, install_url, repos: [],
+ *                       truncated: false } — machine-readable
+ *                       authorized-but-not-installed state; the UI shows
+ *                       the guided-install step, no string-matching needed.
+ *   400 { error, message } — no github_oauth credential stored.
+ *   502 { error, message } — GitHub unreachable / API error.
  */
 export async function handleAuthGithubRepos(
   manager: MirrorManager,
@@ -828,9 +963,58 @@ export async function handleAuthGithubRepos(
       { status: 400 },
     );
   }
-  let result;
+  const token = creds.github_oauth.access_token;
+  let installations;
+  try {
+    installations = await listInstallations(token, fetchImpl);
+  } catch (err) {
+    return Response.json(
+      {
+        error: "Repo list failed",
+        message: (err as Error).message ?? String(err),
+      },
+      { status: 502 },
+    );
+  }
+
+  if (installations.length === 0) {
+    // Authorized but not installed — the device-flow grant alone reaches no
+    // repos. Distinct, machine-readable state (NOT an empty repo list that
+    // looks like "you have no repos").
+    return Response.json(
+      {
+        installed: false,
+        install_url: installUrlForSlug(getGithubAppSlug()),
+        repos: [],
+        truncated: false,
+      },
+      { headers: { "Access-Control-Allow-Origin": "*" } },
+    );
+  }
+
+  const repos: Array<GitHubRepoInfo & { account_login: string; installation_id: number }> = [];
+  let truncated = false;
   try {
-    result = await listRepos(creds.github_oauth.access_token, {}, fetchImpl);
+    for (const installation of installations) {
+      const result = await listInstallationRepos(token, installation.id, {}, fetchImpl);
+      // `GET /user/installations/{id}/repositories` takes no `sort` param
+      // (unlike the old `GET /user/repos?sort=updated` picker source), so
+      // order within each account group ourselves: most-recently-updated
+      // first, so the repo the operator probably wants sits near the top.
+      // ISO-8601 timestamps compare lexicographically. Per-group (not
+      // across the union) so the SPA's account grouping stays contiguous.
+      const sorted = [...result.repos].sort((a, b) =>
+        b.updated_at.localeCompare(a.updated_at),
+      );
+      for (const repo of sorted) {
+        repos.push({
+          ...repo,
+          account_login: installation.account.login,
+          installation_id: installation.id,
+        });
+      }
+      if (result.truncated) truncated = true;
+    }
   } catch (err) {
     return Response.json(
       {
@@ -841,7 +1025,7 @@ export async function handleAuthGithubRepos(
     );
   }
   return Response.json(
-    { repos: result.repos, truncated: result.truncated },
+    { installed: true, repos, truncated },
     { headers: { "Access-Control-Allow-Origin": "*" } },
   );
 }
@@ -850,6 +1034,15 @@ export async function handleAuthGithubRepos(
  * `POST /.parachute/mirror/auth/github/create-repo` — create a new repo on
  * the operator's account, return the new RepoInfo. The SPA flows straight
  * from this into the "repo selected" state.
+ *
+ * With the shared Parachute app this 403s by design (vault#480):
+ * `POST /user/repos` needs Administration:write; the shared app is frozen
+ * at Contents-only. The 403 maps to error_type "app_lacks_admin_permission"
+ * with the guided-manual path (create at github.com/new → add it to the
+ * installation → refresh the picker). The endpoint stays functional for
+ * BYO-app operators whose app grants Administration:write — and per the
+ * install docs, app-created repos auto-join the installation, so their
+ * create→push flow works end-to-end.
  */
 export async function handleAuthGithubCreateRepo(
   req: Request,
@@ -892,6 +1085,20 @@ export async function handleAuthGithubCreateRepo(
       fetchImpl,
     );
   } catch (err) {
+    if (err instanceof GitHubApiError && err.status === 403) {
+      // Expected with the shared Contents-only app: POST /user/repos needs
+      // Administration:write. Actionable, machine-readable mapping — the UI
+      // renders the guided-manual checklist off error_type, not a string.
+      return Response.json(
+        {
+          error: "Create not permitted for this GitHub App",
+          error_type: "app_lacks_admin_permission",
+          message:
+            "The Parachute GitHub App can't create repositories (it only has Contents permission — creating repos needs Administration). Create it manually instead: 1) create a private, uninitialized repo at github.com/new, 2) add it to the app installation (GitHub → Settings → Applications → Configure), 3) refresh the repo list here and pick it.",
+        },
+        { status: 403 },
+      );
+    }
     return Response.json(
       { error: "Create failed", message: (err as Error).message ?? String(err) },
       { status: 502 },
@@ -947,6 +1154,18 @@ export async function handleAuthGithubSelectRepo(
     name,
   );
 
+  // vault#483: linking implies backup intent — the choose-repo re-entry can
+  // be the FIRST credential-linked action for this vault (a credential saved
+  // before history-on-link existed, on a never-configured vault: the #483
+  // "linked but silently inert" state). Run history-on-link here too, BEFORE
+  // the Cut-3/Cut-6 steps below and mirroring handleAuthPat's ordering:
+  // history on (the reload's start() resolves mirror_path so the remote
+  // write below actually lands), then Cut 3 sees an enabled mirror and flips
+  // auto_push, then Cut 6 fires the initial push. An explicitly-disabled
+  // mirror short-circuits all of it (history stays off → maybeEnableAutoPush
+  // no-ops on disabled).
+  const history_enabled = await maybeEnableHistoryOnLink(manager);
+
   // Apply to the mirror dir if running. If the mirror isn't running (no
   // mirror_path), we still consider this a success — the credentials are
   // stored, and the URL will get applied next time the mirror starts.
@@ -980,6 +1199,7 @@ export async function handleAuthGithubSelectRepo(
       // Echo the redacted form back so the SPA can show "pushing to <repo>".
       // No raw token in the response.
       remote: `https://github.com/${owner}/${name}.git`,
+      history_enabled,
       auto_push_was_already_enabled: autoPushChange.was_already_enabled,
       auto_push_enabled: autoPushChange.auto_push_now_enabled,
       initial_push: initialPush,
@@ -988,6 +1208,73 @@ export async function handleAuthGithubSelectRepo(
   );
 }
 
+/**
+ * vault#483 fix 1 — linking implies backup intent. Outcome flag for the
+ * credential-save responses:
+ *   - `true` — history (the mirror) is on: either this link just enabled it
+ *     (never-configured vault) or it was already enabled.
+ *   - `"left_disabled"` — a mirror config exists with `enabled: false`; we
+ *     refuse to silently flip an explicit operator choice. The UI should
+ *     offer the one-click "Turn on history now?" enable.
+ *   - `false` — we tried to enable history but the mirror didn't come up
+ *     (e.g. git missing). Config intent is persisted (PUT semantics); the
+ *     mirror status carries the actionable error.
+ */
+export type HistoryOnLink = true | false | "left_disabled";
+
+/**
+ * When a GitHub credential lands (device-flow grant or PAT save), turn
+ * history on for a vault that has NEVER had a mirror configured — nobody
+ * links GitHub to a vault for any reason other than backing it up. Aaron hit
+ * this live (vault#483): pre-#440 vaults have no mirror-config file, so
+ * linking stored a credential and then... nothing, with the only path out
+ * buried in advanced settings.
+ *
+ * Consent-respecting by design:
+ *   - **No config file** (never configured) → enable the internal mirror
+ *     with the standard defaults (enabled, internal, events, auto_commit on,
+ *     auto_push off — the same shape #440 gives new vaults). Writes through
+ *     `manager.reload()` — the exact path the PUT handler uses — so persist +
+ *     lifecycle-start stay one code path.
+ *   - **Config file exists with enabled:false** → explicit operator choice;
+ *     do NOT flip it. Return `"left_disabled"` so the UI can offer one-click
+ *     enable instead.
+ *   - **Config file exists with enabled:true** → nothing to do.
+ *
+ * The file-existence check (not just the parsed read) is the load-bearing
+ * distinction: an existing-but-malformed file parses to `undefined`, same as
+ * absent — but it still represents operator-touched state, so we treat it as
+ * "exists, not known-enabled" and leave it alone.
+ */
+async function maybeEnableHistoryOnLink(
+  manager: MirrorManager,
+): Promise<HistoryOnLink> {
+  const vaultName = manager.getVaultName();
+  if (!existsSync(mirrorConfigPath(vaultName))) {
+    try {
+      const status = await manager.reload({
+        ...defaultMirrorConfig(),
+        enabled: true,
+      });
+      if (!status.enabled) {
+        console.warn(
+          `[mirror-auth] history-on-link: enabled the mirror config for vault "${vaultName}" but it didn't start: ${status.last_error ?? "unknown error"}`,
+        );
+        return false;
+      }
+      return true;
+    } catch (err) {
+      console.warn(
+        `[mirror-auth] history-on-link: could not enable the mirror for vault "${vaultName}" (non-fatal): ${(err as Error).message ?? err}`,
+      );
+      return false;
+    }
+  }
+  const persisted = readMirrorConfigForVault(vaultName);
+  if (persisted?.enabled) return true;
+  return "left_disabled";
+}
+
 /**
  * Cut 3: when credentials save, flip `auto_push` from false → true on
  * the persisted config. Operators wiring credentials almost certainly

package/src/routes.ts

@@ -15,6 +15,12 @@ import type { Store, Note, QueryOpts } from "../core/src/types.ts";
 import { TAG_EXPAND_MODES, type TagExpandMode } from "../core/src/tag-hierarchy.ts";
 import { listUnresolvedWikilinks } from "../core/src/wikilinks.ts";
 import { getNote, getNotes, getNoteTags, toNoteIndex, filterMetadata, MAX_BATCH_SIZE, validateExtension, ExtensionValidationError } from "../core/src/notes.ts";
+import {
+  parseContentRange,
+  applyContentRange,
+  contentRangeRequiresContent,
+  type ContentRange,
+} from "../core/src/content-range.ts";
 import { attachValidationStatus } from "../core/src/mcp.ts";
 import * as linkOps from "../core/src/links.ts";
 import * as tagSchemaOps from "../core/src/tag-schemas.ts";
@@ -103,6 +109,37 @@ function parseQueryList(url: URL, key: string): string[] | undefined {
   return val ? val.split(",") : undefined;
 }
 
+/**
+ * Parse `?content_offset=` / `?content_length=` (content range — bounded
+ * reads for large notes; unit is UTF-8 bytes, see core/src/content-range.ts
+ * for the codepoint-boundary slicing rules). Returns `{ range: null }` when
+ * neither param is present (response byte-identical to the no-pagination
+ * shape), or `{ error }` (400 INVALID_QUERY) on invalid values or when the
+ * response shape excludes content — range params on a content-less shape
+ * error loudly rather than silently no-op, same policy as `?expand=`.
+ */
+function parseContentRangeQuery(
+  url: URL,
+  includeContent: boolean,
+): { range: ContentRange | null; error?: Response } {
+  try {
+    const range = parseContentRange(
+      parseQuery(url, "content_offset") ?? undefined,
+      parseQuery(url, "content_length") ?? undefined,
+    );
+    if (range && !includeContent) throw contentRangeRequiresContent();
+    return { range };
+  } catch (e: any) {
+    // Duck-type on `name` — core is a separate module, so `instanceof`
+    // is fragile across bundling boundaries (same note as the QueryError
+    // handling in the structured-query path below).
+    if (e && e.name === "QueryError") {
+      return { range: null, error: json({ error: e.message, code: e.code ?? "INVALID_QUERY" }, 400) };
+    }
+    throw e;
+  }
+}
+
 /**
  * Parse the extension query parameter (vault#328). Two accepted shapes:
  *   - `?extension=csv` (single value → string)
@@ -706,12 +743,18 @@ async function handleNotesInner(
           return json({ error: "Note not found", id }, 404);
         }
         const includeContent = parseBool(parseQuery(url, "include_content"), true);
+        const contentRange = parseContentRangeQuery(url, includeContent);
+        if (contentRange.error) return contentRange.error;
         let result: any = includeContent ? { ...note } : toNoteIndex(note);
         const expand = parseExpandParams(url, db, tagScope);
         if (expand && includeContent && typeof result.content === "string") {
           expand.ctx.expanded.add(note.id);
           result.content = expandContent(result.content, expand.ctx, expand.depth);
         }
+        // Content range applies to the FINAL returned content (post-
+        // expansion) — the window the client pages through is the same
+        // document it would have received unpaged.
+        if (contentRange.range && includeContent) applyContentRange(result, contentRange.range);
         result = filterMetadata(result, parseIncludeMetadata(url));
         if (parseBool(parseQuery(url, "include_links"), false)) {
           // Tag-scope: drop links whose neighbor is out of scope so the
@@ -769,6 +812,8 @@ async function handleNotesInner(
         // returns 200 [] (consistent with "no matches"), not 403.
         const results = filterNotesByTagScope(rawResults, tagScope.allowed, tagScope.raw);
         const includeContent = parseBool(parseQuery(url, "include_content"), false);
+        const contentRange = parseContentRangeQuery(url, includeContent);
+        if (contentRange.error) return contentRange.error;
         const inclMeta = parseIncludeMetadata(url);
         let output: any[] = includeContent ? results.map((n) => ({ ...n })) : results.map(toNoteIndex);
         const expand = parseExpandParams(url, db, tagScope);
@@ -780,6 +825,10 @@ async function handleNotesInner(
             }
           }
         }
+        // Content range — per-note, post-expansion (see core/src/content-range.ts).
+        if (contentRange.range && includeContent) {
+          for (const n of output) applyContentRange(n, contentRange.range);
+        }
         if (inclMeta !== undefined && inclMeta !== true) {
           output = output.map((n: any) => filterMetadata(n, inclMeta));
         }
@@ -910,6 +959,8 @@ async function handleNotesInner(
       results = filterNotesByTagScope(results, tagScope.allowed, tagScope.raw);
 
       const includeContent = parseBool(parseQuery(url, "include_content"), false);
+      const contentRange = parseContentRangeQuery(url, includeContent);
+      if (contentRange.error) return contentRange.error;
       const includeLinks = parseBool(parseQuery(url, "include_links"), false);
       const includeAttachments = parseBool(parseQuery(url, "include_attachments"), false);
       const includeLinkCount = parseBool(parseQuery(url, "include_link_count"), false);
@@ -924,6 +975,10 @@ async function handleNotesInner(
           }
         }
       }
+      // Content range — per-note, post-expansion (see core/src/content-range.ts).
+      if (contentRange.range && includeContent) {
+        for (const n of output) applyContentRange(n, contentRange.range);
+      }
       if (inclMeta !== undefined && inclMeta !== true) {
         output = output.map((n: any) => filterMetadata(n, inclMeta));
       }
@@ -952,8 +1007,9 @@ async function handleNotesInner(
         const nodes = output.map((n: any) => ({ id: n.id, path: n.path ?? null, tags: n.tags ?? [] }));
         const edges: { source: string; target: string; relationship: string }[] = [];
         if (includeLinks) {
+          const linksByNote = linkOps.getLinksHydratedForNotes(db, results.map((n) => n.id));
           for (const n of results) {
-            for (const link of linkOps.getLinksHydrated(db, n.id)) {
+            for (const link of linksByNote.get(n.id) ?? []) {
               // Only include edges where source is this note and target is in the result set
               if (link.sourceId === n.id && resultIds.has(link.targetId)) {
                 edges.push({ source: link.sourceId, target: link.targetId, relationship: link.relationship });
@@ -965,13 +1021,19 @@ async function handleNotesInner(
       }
 
       if (includeLinks || includeAttachments) {
+        // Whole-page link hydration in a constant number of queries — the
+        // per-note variant cost (1 link query + 1 summary query + N tag
+        // queries) × page size. 2026-06-10 perf measurements.
+        const linksByNote = includeLinks
+          ? linkOps.getLinksHydratedForNotes(db, output.map((n: any) => n.id))
+          : null;
         const enrichedOut: any[] = [];
         for (const n of output) {
           const enriched: any = { ...n };
-          if (includeLinks) {
+          if (linksByNote) {
             // Tag-scope: strip out-of-scope-neighbor links (no-op unscoped).
             enriched.links = filterHydratedLinksByTagScope(
-              linkOps.getLinksHydrated(db, n.id),
+              linksByNote.get(n.id) ?? [],
               tagScope.allowed,
               tagScope.raw,
             );
@@ -1252,12 +1314,16 @@ async function handleNotesInner(
       return json({ error: "Not found" }, 404);
     }
     const includeContent = parseBool(parseQuery(url, "include_content"), true);
+    const contentRange = parseContentRangeQuery(url, includeContent);
+    if (contentRange.error) return contentRange.error;
     let result: any = includeContent ? { ...note } : toNoteIndex(note);
     const expand = parseExpandParams(url, db, tagScope);
     if (expand && includeContent && typeof result.content === "string") {
       expand.ctx.expanded.add(note.id);
       result.content = expandContent(result.content, expand.ctx, expand.depth);
     }
+    // Content range applies to the FINAL returned content (post-expansion).
+    if (contentRange.range && includeContent) applyContentRange(result, contentRange.range);
     result = filterMetadata(result, parseIncludeMetadata(url));
     if (parseBool(parseQuery(url, "include_links"), false)) {
       // Tag-scope: drop out-of-scope-neighbor links (no-op unscoped).

package/src/routing.ts

@@ -87,6 +87,7 @@ import {
   handleAuthGet,
   handleAuthGithubCreateRepo,
   handleAuthGithubDeviceCode,
+  handleAuthGithubInstallations,
   handleAuthGithubPoll,
   handleAuthGithubRepos,
   handleAuthGithubSelectRepo,
@@ -735,6 +736,13 @@ export async function route(
       if (req.method === "POST") return handleAuthGithubPoll(req, manager);
       return Response.json({ error: "Method not allowed" }, { status: 405 });
     }
+    if (subpath === "/.parachute/mirror/auth/github/installations") {
+      // Install state (vault#480) — which app, installed-anywhere?, install
+      // link, per-account installations. Explicitly-network (probes GitHub);
+      // the offline status read stays on GET /.parachute/mirror/auth.
+      if (req.method === "GET") return handleAuthGithubInstallations(manager);
+      return Response.json({ error: "Method not allowed" }, { status: 405 });
+    }
     if (subpath === "/.parachute/mirror/auth/github/repos") {
       if (req.method === "GET") return handleAuthGithubRepos(manager);
       return Response.json({ error: "Method not allowed" }, { status: 405 });