@openparachute/vault 0.6.3 → 0.6.4-rc.10

package/src/mirror-manager.ts

@@ -369,6 +369,170 @@ async function readCurrentOrigin(repoDir: string): Promise<string | null> {
   return url.length > 0 ? url : null;
 }
 
+// ---------------------------------------------------------------------------
+// Git history read surface (vault#300)
+//
+// The vault is already git-backed via the mirror — one file per note, so
+// `git log` IS a tamper-evident, time-travelable, diffable write history.
+// These helpers SURFACE that history through the admin-gated REST + CLI
+// read paths. No write-path change, no schema change, no new table — the
+// history already exists on disk; we just read it.
+//
+// Same Bun.spawn-git shape as `readCommitsUnpushed` / `readCurrentOrigin`
+// above (spawn array argv, capture stdout, parse) so REST + CLI share ONE
+// implementation and there's no drift between them.
+// ---------------------------------------------------------------------------
+
+/** A single commit in the mirror's history. */
+export interface HistoryEntry {
+  /** Full commit sha. */
+  sha: string;
+  /** ISO-8601 author date (`%aI`). */
+  date: string;
+  /** Commit subject line (`%s`). */
+  message: string;
+}
+
+/** Default cap on how many commits a history read returns. */
+export const HISTORY_DEFAULT_LIMIT = 100;
+/** Hard ceiling — even an explicit `?limit=` can't exceed this. */
+export const HISTORY_MAX_LIMIT = 1000;
+
+/**
+ * Normalize + validate a note path for use as a `git log -- <path>.md`
+ * pathspec. Returns the `<path>.md` argv token, or null when the path is
+ * unsafe / empty.
+ *
+ * The path goes into an ARRAY-spawn argv (no shell), so this isn't guarding
+ * against shell injection — it's guarding against directory traversal
+ * (`..`) and absolute paths escaping the mirror dir, plus normalizing the
+ * leading-slash + trailing-`.md` shape so the pathspec matches the file the
+ * exporter actually wrote (`<note.path>.md`, see portable-md.ts).
+ */
+export function noteHistoryPathspec(notePath: string): string | null {
+  const trimmed = notePath.trim();
+  if (trimmed.length === 0) return null;
+  // Reject absolute paths and traversal — the pathspec must stay inside the
+  // mirror working tree. A `..` segment (or a leading `/`) could otherwise
+  // point `git log` at files outside the vault's note tree.
+  if (trimmed.startsWith("/")) return null;
+  const segments = trimmed.split("/");
+  if (segments.some((s) => s === "..")) return null;
+  // The exporter writes `<note.path>.md`. Accept a path the caller already
+  // suffixed with `.md` (idempotent) or bare; emit the `.md` form either way.
+  const base = trimmed.endsWith(".md") ? trimmed.slice(0, -3) : trimmed;
+  if (base.length === 0) return null;
+  return `${base}.md`;
+}
+
+/**
+ * Read the mirror's commit history via `git log`. Optionally scoped to a
+ * single note's file (`opts.notePath` → `git log --follow -- <path>.md`).
+ *
+ * Returns an ordered (newest-first) array of `{ sha, date, message }`.
+ * Tolerant of the not-yet-a-repo / no-commits-yet cases — those return an
+ * empty array rather than throwing, so a freshly-bootstrapped (or never-
+ * bootstrapped) mirror reads as "no history yet", not a 500.
+ *
+ * `git log` field separators: we use `%H` (full sha), `%aI` (ISO author
+ * date), `%s` (subject). A literal record separator (`\x1f`) joins the
+ * three fields and a literal unit separator (`\x1e`) terminates each record
+ * so a multi-line-unfriendly subject (it isn't — `%s` is the subject line
+ * only) or a commit message containing our delimiters can't desync parsing.
+ *
+ * The git binary preflight is the CALLER's responsibility (REST + CLI both
+ * call `ensureGitAvailable` before this) — but a missing-repo `git log`
+ * exits non-zero, which we map to `[]`, so even an un-preflighted call
+ * degrades to "empty" rather than a crash.
+ */
+export async function readMirrorHistory(
+  repoDir: string,
+  opts: { notePath?: string; limit?: number } = {},
+): Promise<HistoryEntry[]> {
+  const limit = Math.min(
+    Math.max(1, Math.floor(opts.limit ?? HISTORY_DEFAULT_LIMIT)),
+    HISTORY_MAX_LIMIT,
+  );
+  const FIELD_SEP = "\x1f";
+  const RECORD_SEP = "\x1e";
+  const format = `%H${FIELD_SEP}%aI${FIELD_SEP}%s${RECORD_SEP}`;
+  const args = [
+    "log",
+    `--max-count=${limit}`,
+    `--pretty=format:${format}`,
+  ];
+  if (opts.notePath) {
+    const spec = noteHistoryPathspec(opts.notePath);
+    // An unsafe / empty path yields no history rather than an unscoped log.
+    if (spec === null) return [];
+    // `--follow` traces the file across renames (the vault renames note
+    // files when a note's path changes). `--` ends the option list so the
+    // pathspec is never mistaken for a flag.
+    args.push("--follow", "--", spec);
+  }
+  const proc = Bun.spawn(["git", ...args], {
+    cwd: repoDir,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const exitCode = await proc.exited;
+  // Non-zero: not a git repo, no commits yet, or a path with no history.
+  // All map to "empty history" — never a thrown error.
+  if (exitCode !== 0) return [];
+  const out = new TextDecoder().decode(
+    await new Response(proc.stdout).arrayBuffer(),
+  );
+  const entries: HistoryEntry[] = [];
+  for (const record of out.split(RECORD_SEP)) {
+    const trimmed = record.trim();
+    if (trimmed.length === 0) continue;
+    const [sha, date, ...rest] = trimmed.split(FIELD_SEP);
+    if (!sha || !date) continue;
+    entries.push({
+      sha,
+      date,
+      // `%s` never contains FIELD_SEP, but rejoin defensively so a delimiter
+      // that somehow slipped into a subject doesn't truncate the message.
+      message: redactToken(rest.join(FIELD_SEP)),
+    });
+  }
+  return entries;
+}
+
+/**
+ * Read a single past revision of a note file: `git show <sha>:<path>.md`.
+ * Returns the file content at that commit, or null when the path is unsafe,
+ * the sha/path pair doesn't resolve, or git exits non-zero.
+ *
+ * The sha + path both go into an array-spawn argv (no shell). The sha is
+ * validated to a hex-only shape (git accepts abbreviated shas + symbolic
+ * refs, but for this read surface we only allow `[0-9a-f]` so a caller can't
+ * smuggle a `..`-style ref or option-looking token). The path runs through
+ * the same `noteHistoryPathspec` normalization as the log read.
+ */
+export async function showMirrorRevision(
+  repoDir: string,
+  sha: string,
+  notePath: string,
+): Promise<string | null> {
+  const cleanSha = sha.trim();
+  // Hex-only, bounded. Covers full + abbreviated shas; rejects refs,
+  // ranges, and anything option-looking.
+  if (!/^[0-9a-f]{4,64}$/.test(cleanSha)) return null;
+  const spec = noteHistoryPathspec(notePath);
+  if (spec === null) return null;
+  const proc = Bun.spawn(["git", "show", `${cleanSha}:${spec}`], {
+    cwd: repoDir,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const exitCode = await proc.exited;
+  if (exitCode !== 0) return null;
+  return new TextDecoder().decode(
+    await new Response(proc.stdout).arrayBuffer(),
+  );
+}
+
 /**
  * Singleton lifecycle controller. Holds the active mirror config, the
  * resolved path, hook subscriptions (when sync_mode=events), the
@@ -1073,33 +1237,49 @@ export class MirrorManager {
         return;
       }
       // github_oauth: the active token is set, but a repo may not yet be
-      // picked. The select-repo route handler writes the URL; on a
-      // subsequent restart we can't reconstruct the URL without the
-      // owner/repo. Best-effort: if `origin` already points at a github.com
-      // URL, rewrite it with the stored token in case the token rotated.
+      // picked. The select-repo route handler writes the URL onto origin AND
+      // (vault#401) persists owner/name into the credentials struct.
       if (creds.active_method === "github_oauth" && creds.github_oauth) {
-        const current = await readCurrentOrigin(repoDir);
-        if (current && current.includes("github.com")) {
-          // Parse owner/repo out of the current URL.
-          const match = current.match(
-            /github\.com[/:]([^/]+)\/([^/.]+?)(?:\.git)?$/,
-          );
-          if (match) {
-            const [, owner, repo] = match;
-            const { githubAuthedRemoteUrl } = await import("./mirror-credentials.ts");
-            const authed = githubAuthedRemoteUrl(
-              creds.github_oauth.access_token,
-              owner!,
-              repo!,
+        // vault#401: prefer the persisted owner/name. Reconstructing the
+        // remote from credentials alone means the selection survives the
+        // origin being cleared (DELETE /auth then re-OAuth) across a restart —
+        // the bug class where regex-parsing the origin silently lost the repo.
+        const persistedOwner = creds.github_oauth.owner;
+        const persistedName = creds.github_oauth.name;
+        let owner: string | undefined;
+        let repo: string | undefined;
+        if (persistedOwner && persistedName) {
+          owner = persistedOwner;
+          repo = persistedName;
+        } else {
+          // Back-compat fallback: credentials written before #401 don't carry
+          // owner/name. Parse them out of the current github.com origin (the
+          // pre-#401 behavior) when origin is still present.
+          const current = await readCurrentOrigin(repoDir);
+          if (current && current.includes("github.com")) {
+            const match = current.match(
+              /github\.com[/:]([^/]+)\/([^/.]+?)(?:\.git)?$/,
             );
-            const result = await applyToGitRemote(repoDir, authed);
-            if (!result.ok) {
-              console.warn(
-                `[mirror] could not refresh github_oauth remote URL (non-fatal): ${result.error}`,
-              );
+            if (match) {
+              owner = match[1];
+              repo = match[2];
             }
           }
         }
+        if (owner && repo) {
+          const { githubAuthedRemoteUrl } = await import("./mirror-credentials.ts");
+          const authed = githubAuthedRemoteUrl(
+            creds.github_oauth.access_token,
+            owner,
+            repo,
+          );
+          const result = await applyToGitRemote(repoDir, authed);
+          if (!result.ok) {
+            console.warn(
+              `[mirror] could not refresh github_oauth remote URL (non-fatal): ${result.error}`,
+            );
+          }
+        }
       }
     } catch (err) {
       console.warn(

package/src/mirror-routes.test.ts

@@ -912,6 +912,84 @@ describe("auth credential routes — credential-save side-effects (Cuts 3 + 6)",
     await manager.stop();
   }, 30_000);
 
+  test("vault#401: owner/name survive a cleared origin + restart (persisted in creds, not just the git remote)", async () => {
+    // The bug: pre-#401, select-repo wrote owner/name ONLY into the git
+    // origin URL. On restart, applyCredentialsToRemote regex-parsed them back
+    // out of the origin — so clearing the origin (DELETE /auth → re-OAuth
+    // without re-selecting) silently lost the repo even with a valid token.
+    // Now select-repo persists owner/name into the credentials struct, and
+    // applyCredentialsToRemote prefers the persisted values. With the origin
+    // cleared, a restart still reconstructs the github.com remote.
+    home = tmp("mirror-selectrepo-persist-");
+    const { manager, deps } = makeManager(home);
+    const cfg = {
+      ...defaultMirrorConfig(),
+      enabled: true,
+      location: "internal" as const,
+      sync_mode: "manual" as const,
+      auto_commit: false,
+      auto_push: false,
+    };
+    // The manager reads config via deps.readMirrorConfig (in-memory); the
+    // route's history-on-link keys off the real per-vault file's existence.
+    // Seed both, same as the autopush test above.
+    deps.writeMirrorConfig(cfg);
+    writeMirrorConfigForVault("default", cfg);
+    await manager.start();
+    const mirrorPath = manager.getStatus().mirror_path;
+    expect(mirrorPath).toBeTruthy();
+
+    writeCredentials("default", {
+      active_method: "github_oauth",
+      github_oauth: {
+        access_token: "gho_persisttoken12345",
+        scope: "repo",
+        authorized_at: "2026-05-28T03:14:15.000Z",
+        user_login: "aaron",
+        user_id: 1,
+      },
+      pat: null,
+    });
+
+    const res = await handleAuthGithubSelectRepo(
+      new Request("http://x/select", {
+        method: "POST",
+        body: JSON.stringify({ owner: "aaron", name: "backup-repo" }),
+      }),
+      manager,
+    );
+    expect(res.status).toBe(200);
+
+    // The fix: owner/name persisted into the credentials struct (not just origin).
+    const persisted = readCredentials("default");
+    expect(persisted?.github_oauth?.owner).toBe("aaron");
+    expect(persisted?.github_oauth?.name).toBe("backup-repo");
+
+    // Simulate the DELETE /auth + re-OAuth-without-reselect path: the OAuth
+    // token survives, but the git origin gets cleared.
+    Bun.spawnSync(["git", "remote", "remove", "origin"], { cwd: mirrorPath! });
+    const afterClear = Bun.spawnSync(["git", "remote", "get-url", "origin"], {
+      cwd: mirrorPath!,
+    });
+    expect(afterClear.exitCode).not.toBe(0); // origin is gone
+
+    // Restart — applyCredentialsToRemote runs again. Pre-#401 it would find no
+    // origin to parse and leave the remote unset; post-#401 it rebuilds from
+    // the persisted owner/name.
+    await manager.stop();
+    await manager.start();
+
+    const reapplied = Bun.spawnSync(["git", "remote", "get-url", "origin"], {
+      cwd: mirrorPath!,
+    });
+    expect(reapplied.exitCode).toBe(0);
+    const reappliedUrl = reapplied.stdout.toString().trim();
+    // The remote was reconstructed from persisted owner/name (token embedded,
+    // not asserted here). Without persistence this would be empty.
+    expect(reappliedUrl).toContain("github.com/aaron/backup-repo");
+    await manager.stop();
+  }, 30_000);
+
   test("select-repo is a no-op for auto_push when mirror is disabled", async () => {
     // Operator wiring credentials before flipping the mirror on — don't
     // mutate auto_push behind their back.

package/src/mirror-routes.ts

@@ -34,7 +34,11 @@ import {
   validateMirrorConfigShape,
   type MirrorConfig,
 } from "./mirror-config.ts";
-import type { MirrorManager } from "./mirror-manager.ts";
+import {
+  readMirrorHistory,
+  showMirrorRevision,
+  type MirrorManager,
+} from "./mirror-manager.ts";
 import { getMirrorManager } from "./mirror-registry.ts";
 import {
   applyToGitRemote,
@@ -296,6 +300,183 @@ export async function handleMirrorPushNow(
   );
 }
 
+/**
+ * `GET /vault/<name>/.parachute/mirror/history` — surface the mirror's git
+ * commit history (vault#300).
+ *
+ * The vault is already git-backed via the mirror (one file per note), so
+ * `git log` IS a tamper-evident, diffable write history. This endpoint
+ * SURFACES it through the admin gate — it's a read-only ops/forensics
+ * surface, not a content read path (hence admin, not read, scoped upstream).
+ *
+ * Query params:
+ *   - `?path=<note.path>` — scope the log to a single note's file
+ *     (`git log --follow -- <path>.md`). An unsafe path (traversal /
+ *     absolute) yields an empty list, never an unscoped log.
+ *   - `?limit=<n>` — cap the number of commits (default
+ *     HISTORY_DEFAULT_LIMIT, clamped to HISTORY_MAX_LIMIT).
+ *
+ * Response: 200 `{ history: [{ sha, date, message }], mirror_path,
+ * path?, limit }`. Degrades gracefully:
+ *   - mirror disabled / no path resolved → 200 with empty history + a
+ *     `note` explaining the mirror isn't initialized (not a 500).
+ *   - git not installed → 503 git_not_installed (consistent with the other
+ *     mirror routes).
+ *   - no commits yet / path with no history → 200 empty history.
+ */
+export async function handleMirrorHistory(
+  req: Request,
+  manager: MirrorManager,
+): Promise<Response> {
+  const url = new URL(req.url);
+  const pathParam = url.searchParams.get("path") ?? undefined;
+  const limitParam = url.searchParams.get("limit");
+  let limit: number | undefined;
+  if (limitParam !== null) {
+    const n = Number(limitParam);
+    if (!Number.isInteger(n) || n <= 0) {
+      return Response.json(
+        {
+          error: "Invalid limit",
+          field: "limit",
+          message: "limit must be a positive integer.",
+        },
+        { status: 400 },
+      );
+    }
+    limit = n;
+  }
+
+  const status = manager.getStatus();
+  // No resolved mirror path means the mirror was never enabled /
+  // bootstrapped for this vault — there's no git repo to read. Return an
+  // empty history with an explanatory note rather than a 500/404; the
+  // caller (SPA / CLI) renders "no history yet, enable backup to start".
+  if (!status.mirror_path) {
+    return Response.json(
+      {
+        history: [],
+        mirror_path: null,
+        ...(pathParam ? { path: pathParam } : {}),
+        note: "Mirror is not initialized for this vault — no git history exists yet. Enable history (backup) to start recording write history.",
+      },
+      { headers: { "Access-Control-Allow-Origin": "*" } },
+    );
+  }
+
+  // Preflight git — the helper degrades a missing repo to [], but a
+  // git-less server should get the friendly, actionable 503 (same shape as
+  // the import / PUT routes) rather than a silently-empty list.
+  try {
+    ensureGitAvailable();
+  } catch (err) {
+    if (err instanceof GitNotInstalledError) {
+      return Response.json(
+        {
+          error: "git not installed",
+          error_type: "git_not_installed",
+          message: err.message,
+        },
+        { status: 503 },
+      );
+    }
+    throw err;
+  }
+
+  const history = await readMirrorHistory(status.mirror_path, {
+    notePath: pathParam,
+    limit,
+  });
+  return Response.json(
+    {
+      history,
+      mirror_path: status.mirror_path,
+      ...(pathParam ? { path: pathParam } : {}),
+      ...(limit !== undefined ? { limit } : {}),
+    },
+    { headers: { "Access-Control-Allow-Origin": "*" } },
+  );
+}
+
+/**
+ * `GET /vault/<name>/.parachute/mirror/history/show?sha=<sha>&path=<note.path>`
+ * — read a single note file at a past revision (`git show <sha>:<path>.md`).
+ * The companion to `/history`: history lists the commits, this reads what a
+ * note looked like at one of them. Admin-gated (vault#300).
+ *
+ * Query params (both required):
+ *   - `sha` — a commit sha (hex, validated in `showMirrorRevision`).
+ *   - `path` — the note path (normalized to `<path>.md`).
+ *
+ * Response:
+ *   200 `{ sha, path, content }` — the file content at that revision.
+ *   400 — missing sha/path.
+ *   404 — the sha/path pair doesn't resolve (unknown sha, note didn't
+ *         exist at that commit, or an unsafe path).
+ *   503 — git not installed.
+ */
+export async function handleMirrorHistoryShow(
+  req: Request,
+  manager: MirrorManager,
+): Promise<Response> {
+  const url = new URL(req.url);
+  const sha = url.searchParams.get("sha")?.trim() ?? "";
+  const notePath = url.searchParams.get("path")?.trim() ?? "";
+  if (sha.length === 0 || notePath.length === 0) {
+    return Response.json(
+      {
+        error: "sha and path required",
+        message:
+          "Provide both `sha` (a commit from /history) and `path` (the note path) query params.",
+      },
+      { status: 400 },
+    );
+  }
+
+  const status = manager.getStatus();
+  if (!status.mirror_path) {
+    return Response.json(
+      {
+        error: "Mirror not initialized",
+        message:
+          "No git history exists for this vault yet — enable history (backup) first.",
+      },
+      { status: 404 },
+    );
+  }
+
+  try {
+    ensureGitAvailable();
+  } catch (err) {
+    if (err instanceof GitNotInstalledError) {
+      return Response.json(
+        {
+          error: "git not installed",
+          error_type: "git_not_installed",
+          message: err.message,
+        },
+        { status: 503 },
+      );
+    }
+    throw err;
+  }
+
+  const content = await showMirrorRevision(status.mirror_path, sha, notePath);
+  if (content === null) {
+    return Response.json(
+      {
+        error: "Revision not found",
+        message: `No content for ${notePath} at ${sha} — the sha may be unknown, the note may not have existed at that commit, or the path is invalid.`,
+      },
+      { status: 404 },
+    );
+  }
+  return Response.json(
+    { sha, path: notePath, content },
+    { headers: { "Access-Control-Allow-Origin": "*" } },
+  );
+}
+
 /**
  * Convenience for tests + future callers: build the GET response from a
  * known-good config without needing a real MirrorManager.
@@ -1200,6 +1381,19 @@ export async function handleAuthGithubSelectRepo(
     }
   }
 
+  // vault#401: persist the selected owner/name INTO the credentials struct,
+  // not only into the git origin URL. Pre-#401 the selection lived solely in
+  // the origin URL; `applyCredentialsToRemote` regex-parsed it back out on
+  // restart, so clearing the origin (e.g. `DELETE /auth` then re-OAuth without
+  // re-selecting) silently lost the repo even with a still-valid token. Saving
+  // it here lets the restart path reconstruct the remote from credentials
+  // alone. Write before the remote-apply so the persisted selection survives
+  // even if the apply later fails.
+  writeCredentials(manager.getVaultName(), {
+    ...creds,
+    github_oauth: { ...creds.github_oauth, owner, name },
+  });
+
   // Reach into mirror-credentials.ts for the authed URL builder.
   const { githubAuthedRemoteUrl } = await import("./mirror-credentials.ts");
   const authedUrl = githubAuthedRemoteUrl(